[nfsv4] Re: Review: draft-ietf-nfsv4-uncacheable-directories-11

[Thomas Haynes <[e-mail]>]

On Mon, Sep 21, 2026 at 01:33:49PM -0800, Chuck Lever wrote:
> Posted as an individual contributor, not as a co-chair or document steward.
> 
> I re-read -11 end to end and came away with the mechanism the author intended only after several wrong turns. The normative text in Section 5.1 is clear once reached. What sends a reader the wrong way is the framing around it, and the same wrong turns appear in recent email list discussion, so IMO the framing needs improvement.
> 
> 1. The Abstract and the Introduction describe the client's obligation only negatively. The Abstract ends:
> 
>    ... an
>    honoring client goes to the server for each enumeration, and does not
>    report an entry's attributes from a value it held before that
>    READDIR.
> 
> The last paragraph of Section 1 takes the same direction ("reporting dirent metadata a client held beforehand is unsuitable"). Neither sentence says where the reported values do come from, so a reader takes "not from a value held before" together with the word "uncacheable" and concludes the client is to ignore or discard what the READDIR carries.
> 
> However Section 5.1 says the opposite: the client names the attributes in attr_request and reports what that READDIR returned, and may retain them afterwards. One sentence naming the positive source would prevent the misreading, for example: "an honoring client issues a READDIR on each enumeration and reports each entry's attributes as that READDIR returned them, rather than from any value it held earlier."
> 
> 2. The attribute comprises two linked rules, but the attribute name and draft title advertise only one of them. Section 5.1 requires (a) that each application enumeration of a marked directory is satisfied by a READDIR rather than from cached results, and (b) that the attributes that READDIR returns displace attributes the client previously held for the entry. Rule (a) is what changes client behaviour today, because RFC 8881 Section 10.8.2 lets a client answer an application readdir from a cached snapshot validated by the directory's change attribute, so no on-the-wire READDIR is needed. Rule (b) alone would not help, since a client could send the READDIR with a minimal attr_request and answer the stats from its attribute cache.
> 
> "Uncacheable dirent metadata" names rule (b), and Section 5.1 permits retention, so the name is both incomplete and slightly misleading. I am not asking for a rename at this stage. I am recommending that Section 5 state, near the top, that the rule has these two halves and that the enumeration half is the one a client cannot be made to do today.
> 
> 3. The change attribute keeps surfacing as the mechanism because the problem is explained in terms of it. Section 2, Section 3 and the Abstract all explain attribute cache staleness by saying the directory's change attribute does not move on child writes. A reader then naturally tries to fit the fix into the same frame: does the file's cache now consult the parent's change attribute, or does a READDIR act as a bump of every child's change attribute?
> 
> Neither of those is what Section 5.1 mandates. The invalidation event is the enumeration itself, unconditionally, for every entry the READDIR returns, and between enumerations nothing changes. Section 5.1's paragraph on the change attribute says the semantics are unchanged but does not say what replaces them as the trigger. A sentence such as "the event that invalidates a held value is the enumeration, not any change attribute" would improve clarity.
> 
> 4. Which attributes are in scope is stated in Section 3 but obscured by the examples. The Abstract and Section 2 explicitly name size and timestamps, and Section 5.1 applies to "a value of a dirent metadata attribute", where Section 3 defines that term as the whole class a READDIR can carry. A reader who reaches Section 5.1 from the Abstract cannot tell whether size and time_modify are the whole list or examples from it. Saying "for example" or "including" at the first mention would settle it.
> 
> It is also worth stating explicitly that the file's own change attribute is in the class, because a client that compares change attributes before accepting a fattr (Linux does) needs to know that the READDIR's value wins for it too, or its newer-wins comparison could reject the rest.
> 
> 5. Section 2 does not quite answer why a client does not already behave as if DIRENT_METADATA is always set. The obvious objection is that a client could revalidate cheaply with a GETATTR of the parent and refetch only when needed. The missing sentence is that the parent's change attribute cannot distinguish a directory with a thousand file writers from a quiet one, so the client has no basis for a per-directory choice and is left with a per-mount policy. Section 2 says NFSv4.2 has "no in-band way" to tell the client, which is true but does not explain why the client cannot work it out for itself.
> 
> 6. A client that requests only each file's change attribute in the READDIR, invalidates the entries whose value moved, and fetches attributes on demand also conforms, by the "or obtains them afterwards" branch. The SHOULD's rationale, that fetching afterwards "costs one GETATTR per entry", holds only for workloads that stat every entry (ls -l). Those are the Section 2 workloads, so the SHOULD is right for them, but the text would be less puzzling if it said that the per-entry cost applies to listings that read every entry's size and time_modify, which is what a backup or sync pass does.
> 
> As far as I can tell, these are all editorial and organizational changes that improve clarity without altering the technical aspects of the document.
> 
> 
> --
> Chuck Lever (Come to NFS bake-a-thon! https://nfsv4bat.org)
> _______________________________________________
> nfsv4 mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]


Drafted with AI assistance; the RFC 8881 quotations below are checked
against the published text.

Five of the six are in -12 as you framed them.  The sixth I have only
half taken, and the missing half is not a drafting problem: it exposes
something already wrong in -11.

1. The Abstract and the Introduction now say where a reported value
comes from.  The Abstract closes "an honoring client enumerates by
READDIR and reports each entry's attributes as that READDIR returned
them, rather than from a value it held earlier."

2. Section 5 states the two halves before pointing at 5.1, and names
the enumeration half as the one that changes what a client may do
today, with the 10.8.2 reason.

3. The change-attribute paragraph in 5.1 now says the event that
renders a held value unreportable for an entry is the enumeration that
returns that entry, whatever any change attribute does.

5. Section 2 says why a client cannot work it out for itself: the
directory's change attribute reads the same for a directory taking
writes from a thousand nodes and for one nobody is touching, so there
is no basis for a per-directory choice and the client is left with one
policy per mount.

6. The attr_request SHOULD now says when the cost applies -- a listing
or a directory-tree synchronization pass, which reads the size and
time_modify of every entry -- and that a client expecting no such read
may obtain them afterwards.

4. Definitions now lists the class with "including ... and the file's
own change attribute", and Section 2 points at that class rather than
reading as though size and time_modify were the whole of it.

What I have left out is the consequence you drew from it, that the
READDIR's value wins for a client doing a newer-wins comparison.  I
cannot state that without a conflict-resolution rule the document does
not have, and as a blanket rule it would be wrong.  RFC 8881 Section
10.6:

   The client may maintain a cache of modified attributes for those
   attributes intimately connected with data of modified regular files
   (size, time_modify, and change).

and

   Therefore, extending a file by writing data to the local data cache
   is reflected immediately in the size as seen on the client without
   this change being immediately reflected on the server.

A client with dirty pages for an entry holds a newer size than a
READDIR returns.  Telling it the arriving value wins makes it report
the server's older size for exactly the files it is writing -- in the
Section 2 workload, every file it writes.

That is a defect in -11 independent of your item.  The MUST NOT in 5.1
reaches a value "received before the READDIR ... whatever operation
supplied that value", and its only carve-out is the OPEN_DELEGATE_WRITE
paragraph.  Write-back without a delegation is not covered, and 10.6 is
explicit that it is legal.

So -12 carries the membership sentence and not the consequence, and I
would rather the WG looked at the carve-out than have me pick a rule
for it.  Two shapes:

(a) exempt the three attributes 10.6 names, where the client's value is
    its own unflushed modification, alongside the existing delegation
    exemption; or

(b) scope the rule to values the client received from the server, so
    its own modifications are outside it altogether.

(b) is the smaller change and I think closer to what the rule was
always for, but I would rather hear which the group prefers than pick.

A second gap, unrelated to your six.  5.1 turns on the phrase "an
object that is not a directory", and RFC 8881 Section 5.8.1.2 defines
that phrase: "The phrase 'is a directory' means that the object's type
attribute is NF4DIR or NF4ATTRDIR."  So as written the attribute
already applies to named attribute directories, and a server owes a
settable value for one.  That is not absurd -- OPENATTR yields an
NF4ATTRDIR filehandle and Section 5.3 has READDIR enumerate it, with
NF4NAMEDATTR entries carrying attributes of their own -- but I did not
choose it, and nothing in the document says a word about it.

My inclination is to scope the attribute to NF4DIR explicitly, on the
grounds that nobody has described a named attribute directory enumerated
hot enough to need this, and a later document can widen an attribute
more easily than narrow one.  But it is the WG's to choose, and I would
rather ask than have -12 settle it by inheriting a definition I had not
noticed.

Mohamed Boucadair caught the same shape of thing in the files
document -- it said NF4REG where RFC 7862 Section 6.1 defines a regular
file as NF4REG or NF4NAMEDATTR -- so this is the sort of question the
IESG asks.  -12 also takes four changes that review produced and this
document would otherwise be asked for later: the RFC 8178 Section 6
statement that extending NFSv4.2 does not update it, a definition of
revalidation, the error a server returns for a SETATTR its policy
refuses, and a statement that no particular policy is required.

Tom

-- 
Tom Haynes <[e-mail]>