Subject: [apps-discuss] Review of: draft-ietf-appsawg-file-scheme-11

From: Dave Crocker <[email-masked]>
Date: Sat, 13 Aug 2016 17:05:07 -0700

Review:   The file URI Scheme
ID:       draft-ietf-appsawg-file-scheme-11
Review Date:  13 Aug 2016
Reviewer:     D. Crocker <[email-masked]>

Summary
-------

This is a followup to my Document Shepherd review of the -05 version on 
12 April 2016.

The document changes are effective.  I found only a few places to make a 
few suggestions, mostly minor.[*]

There is one significant concern, in Section 3, which continues from the 
previous review and I've suggested replacement text and this is the 
presence of normative language.

After resolution of this one concern, the document will be ready for 
publication.

Nice job!

d/

> 1.1.  Notational Conventions
>
>    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
>    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
>    document are to be interpreted as described in [RFC2119].
>
>    Throughout this document the term "local file" is used to describe
>    files that can be accessed through the local file system API using
>    only the information included in the file path, not relying on other
>    information such as network addresses.  It is important to note that
>    a local file may not be physically located on the local machine, for
>    example if a networked file system is transparently mounted into the
>    local file system.
>
>    The term "local file URI" is used to describe file URIs which have no
>    authority component, or where the authority is the special string

probably should be: "authority" component, given the surrounding 
conventions used in this paragraph.

>    "localhost" or a fully qualified domain name that resolves to the
>    machine from which the URI is being interpreted (Section 2).
>
> 2.  Syntax
...
>       file-URI       = file-scheme ":" file-hier-part
>       file-scheme    = "file"
>
>       file-hier-part = ( "//" auth-path )
>                      / local-path
>
>       auth-path      = [ file-auth ] path-absolute

Hmmm.  I wondered how file-auth and path-absolute were separated, but 
see from Section 3.3 of RFC 3986 that path-absolute beings with a "/".

I think this means that if there is no file-auth, the beginning will be 
"file:///" etc.  Is that intended?

>
>       local-path     = path-absolute
>
>       file-auth      = "localhost"
>                      / host
>
>    The "host" is the fully qualified domain name of the system on which
>    the file is accessible.  This allows a client on another system to
>    know that it cannot access the file system, or perhaps to use some

   perhaps to use -> or perhaps that they need to use

>    other local mecahnism to access the file.
...
>
>    Some file systems have case-sensitive file naming and some do not.
>    As such the file URI scheme supports case sensitivity, in order to
>    retain the case as given.  Any transport-related handling of the file
>    URI scheme MUST retain the case as given.  Any mapping to or from a
>    case-insensitive form is soley the responsibility of the

  soley -> solely

>    implementation processing the file URI on behalf of the referenced
>    file system.
>
>    Some file systems allow directory objects to be treated as files in
>    some cases.  This can be reflected in a file URI by omitting the
>    trailing slash "/" from the path.  Be aware that merging a relative

oh?  I would have thought it would have required retaining a trailing 
"/" if the URI is for a folder, and dropping it if it refers to a file...

>    URI reference to such a base URI as per Section 5.2 of [RFC3986]
>    could remove the directory name from the resulting target URI.
...

> 3.  Operations Involving file URIs

I am going to again raise a concern about this.  The document isn't 
providing enough detail about the processing of URIs to be meaningful, 
nevermind normative.  (I can even argue that the normative directive 
here is wrong in various write-only cases.  One might respond that 
that's why it's a SHOULD rather than MUST, but my view of SHOULDs is 
that violating them needs to be exceptional, and activities like 
write-only sensor networks don't strike me as that special.

In other words, I encourage remove all normative language here.  I 
believe the easiest and most reasonable action is to remove the first 
two sentences, below, and start with "See the".

...

> 4.  File System Name Encoding
>
>    File systems use various encoding schemes to store file and directory
>    names.  Many modern file systems store file and directory names as
>    arbitrary sequences of octets, in which case the representation as an
>    encoded string often depends on the user's localization settings, or
>    defaults to UTF-8 [STD63].
>
>    When a file URI is produced, characters not allowed by the syntax in
>    Section 2 SHOULD be percent-encoded as characters using UTF-8
>    encoding, as per [RFC3986], Section 2.5.
>
>    However, encoding information for file and/or directory names might
>    not be available.  In these cases, implementations MAY use heuristics
>    to determine the encoding.  If that fails, they SHOULD percent-encode
>    the raw bytes of the label directly.

An IETF protocol that has normative language allowing heuristics is 
asking for all sorts of problems.  And here I believe it isn't 
necessary, though I think I understand the difficulty you are trying to 
deal with.

Consider this as a replacement for the above paragraph:

      A decision not to use percent-encoding is outside the scope of 
this specification.  It will typically require use of heuristics or 
explicit knowledge about the way the string will be processed.

d/

[*] I'll mention that I've just come off of reviewing 3 other documents 
that I found highly problematic and was probably in an unusually 
cantankerous mood when reviewing the file scheme revision here.  So I 
actually put some effort into looking for clarity and correctness 
problems, especially in the core part of the document, Section 2.  It 
was really quite pleasant to /fail/ in that effort.  Thanks!

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Matthew Kerwin <[email-masked]>
Date: Sun, 14 Aug 2016 20:16:59 +1000

On 14 August 2016 at 10:05, Dave Crocker <[email-masked]> wrote:

> This is a followup to my Document Shepherd review of the -05 version on 12
> April 2016.
>
​No worries, will change that.​

> Hmmm.  I wondered how file-auth and path-absolute were separated, but see
> from Section 3.3 of RFC 3986 that path-absolute beings with a "/".
>
​Yes; RFC1738 file URIs look like "file:///foo/bar" (meaning file "bar" in
directory "/foo").

>   perhaps to use -> or perhaps that they need to use
​ACK​

>    other local mecahnism to access the file.

​Heh, "mecahnism" is a typo too.​

>>    case-insensitive form is soley the responsibility of the
​ACK​

> oh?  I would have thought it would have required retaining a trailing "/"
> if the URI is for a folder, and dropping it if it refers to a file...
>
>
​Unless you're intentionally treating the directory as a file. In the UNIX
path "/foo/bar", 'bar' might be a directory, even without a trailing "/";
and if you used that path to create a file URI like "file:///foo/bar" you
need to be careful with relative references.

I think I will just delete the paragraph; it doesn't add much (except for
confusion.) It's certainly not worth a couple of round-trips to refine.​

> nevermind normative.  (I can even argue that the normative directive here
> is wrong in various write-only cases.  One might respond that that's why
> it's a SHOULD rather than MUST, but my view of SHOULDs is that violating
> them needs to be exceptional, and activities like write-only sensor
> networks don't strike me as that special.
>
> In other words, I encourage remove all normative language here.  I believe
> the easiest and most reasonable action is to remove the first two
> sentences, below, and start with "See the".
>
>
​That works for me.​

> An IETF protocol that has normative language allowing heuristics is asking
> for all sorts of problems.  And here I believe it isn't necessary, though I
> think I understand the difficulty you are trying to deal with.
>
>      A decision not to use percent-encoding is outside the scope of this
> specification.  It will typically require use of heuristics or explicit
> knowledge about the way the string will be processed.
>
>
​I'm happy with that, but I'll say "...not to use percent-encoded
UTF-8...".​

> actually put some effort into looking for clarity and correctness problems,
> especially in the core part of the document, Section 2.  It was really
> quite pleasant to /fail/ in that effort.  Thanks!
>
>
​I appreciate the effort, and the outcome. Thank you too.  I'll submit this
version (-12) right now.​

>   Brandenburg InternetWorking
​Cheers​
-- 
  Matthew Kerwin
  http://matthew.kerwin.net.au/

---

From: Dave Crocker <[email-masked]>
Date: Sun, 14 Aug 2016 07:05:10 -0700

On 8/14/2016 3:16 AM, Matthew Kerwin wrote:
> I'll submit this version (-12) right now.​

Indeed you did.  And I've just submitted the Shepherd's report to 
initiate the IESG process.

Again, nice job.

d/

-- 

   Dave Crocker