Re: A proposal for OPEN

[Joseph Galbraith <galb-list%vandyke.com@localhost>]

> > access_flags
> >     The access_flags is two seperate bit fields.  Bit values
> >     in the 0xFFFF0000 mask are required, and if they can not
> >     be supported, the operation MUST fail.
> >
> >     Bit values in the 0x0000FFFF mask are requested, but if they
> >     can not be supported the operation SHOULD continue.
> >
> >     Clients MUST NOT send any undefined bits in the access_flags
> >     field.  Servers should ignore any bits not specified here.
> >
> >     Future IETF action may add additional bits without
> >     reving the version number.
>
>
> This isn't really self-consistent.

Arghh... of course, you are right.  I failed to go back and
rework that section.

> I'd suggest something like this:
>
> The access_flags is two separate bit fields.  Bit values in the 
> 0xffff0000 mask are required, while bit values in the 0x000ffff mask are 
> requested. Clients must not send any undefined bits in the access_flags 
> field.
>
> Bit values in the 0xffff0000 mask are required; if a flag in this range 
> is set and cannot be supported by the server, the operation MUST fail.
>
> Bit values in the 0x0000ffff mask are requested; if a flag in this range 
> is set and its meaning is not known to the server, the operation MUST 
> continue as if the flag had not been set.  If such a flag is set and its 
> meaning is known to the server, but cannot be supported, the server MAY 
> report an appropriate error or allow the operation to continue as if the 
> flag had not been set.
>
> Future IETF action may add additional bits without any need to change 
> the protocol version number.

Excellent.

> [ I think something slightly stronger is warranted -- the available 
> space is small, and should probably only be used for "mainstream" 
> revisions of the protocol and not private extensions. ]

Yes, this sounds reasonable.

> >     The following required fields are defined:
> >         ACCESS_DISPOSITION    = 0x00070000
> >             CREATE_NEW        = 0x00000000
> >             CREATE_OVERWRITE  = 0x00010000
> >             OPEN_EXISTING     = 0x00020000
> >             OPEN_OR_CREATE    = 0x00030000
> >             TRUNCATE_EXISTING = 0x00040000
> >         ACCESS_APPEND_DATA    = 0x00080000
>
>
> The meanings of these are more or less obvious, but they should be 
> spelled out, I think.  In terms of traditional UNIX open flags, I think 
> these mean:
>
> CREATE_NEW = O_CREAT | O_EXCL
> CREATE_OVERWRITE = O_CREAT | O_TRUNC
> OPEN_EXISTING = 0
> OPEN_OR_CREATE = O_CREAT
> TRUNCATE_EXISTING = O_TRUNC
>
> ACCESS_APPEND_DATA = O_APPEND
>
> Is this correct?

Yes.  I'll spell it out in the draft.

> Note that the semantics of ACCESS_APPEND_DATA are not entirely clear
> [...]

You raise a good point.  How about:

ACCESS_APPEND_DATA_ATOMIC = 0x00080000
ACCESS_APPEND_DATA        = 0x00100000

ACCESS_APPEND_DATA_ATOMIC
ACCESS_APPEND_DATA
    Data is always written at the end of the file.  The
    offset field of the SSH_FXP_WRITE requests are ignored.

    If the ATOMIC flag is used, then data must be written
    atomically to the end of the file without any chance of
    conflict with another appender.

    If the APPEND_DATA flag is used, atomic append is not
    required, but the server MAY still use atomic appends
    if it so chooses.

    Clients should balance the possibility that a server
    may not support atomic appends against the possibility
    of other writers conflicting.  If the file is not opened
    with SHARE_WRITE, there is no need for atomic appends.

> >     The following required fields are defined:
> >         ACCESS_SHARE_READ    = 0x00000001
> >         ACCESS_SHARE_WRITE   = 0x00000002
> >         ACCESS_SHARE_DELETE  = 0x00000004
>
>
> The meanings of these are not obvious to me, probably because they're 
> drawn from some Windows terminology with which I'm not familiar.

  ACCESS_SHARE_READ
      This flag indicates that client is willing to allow
      other readers of the file to simultaneously co-exist.

  ACCESS_SHARE_WRITE
      This flag indicates that client is willing to allow
      other writers of the file to simultaneously co-exist.

  ACCESS_SHARE_DELETE
      This flag indicates that client is willing to allow
      the file to be deleted while it is accessing it.

  For example, to display a log file that is being updated
  by a daemon process, the client would open the file for
  READ_DATA access, and specify that it was will to allow
  other writers (the daemon process) by specifying
  ACCESS_SHARE_WRITE.

  Previous versions of the protocol did not support these
  options, and so the behavior was implementation dependant.
  Clients that do not care about this, or wish to continue
  to leave the decision up to the server should specify
  all three sharing bits.

  If the client requests an exclusive access (does not
  set one of the share bits), but the server can not
  provide the such locking, it SHOULD fail the request.

  However, if the client is willing to share access, but
  the server does not support this kind of sharing, it
  SHOULD allow the request to succeed anyway.

Another alternative would be to reverse the fields (I'm
familiar with the windows varient, but remember a time
when I found them frustrating.)  Would people find the
following easier to parse:

  ACCESS_READ_LOCK
  ACCESS_WRITE_LOCK
  ACCESS_DELETE_LOCK
    The client wishes to be the lock out other reader, writers,
    writers or deleters.

    For example, the open will fail if another process has
    opened the file for WRITE access and the client requests
    a write lock.

    To display a log file being written to by a daemon process,
    a client would specify READ_DATA accesses, and would specify
    no locking.

    If the server can not provide the locking requested, it
    MUST fail the request.

Now that I've written it, I think maybe I prefer the LOCK variant.
What do other people think?

- Joseph