3.3.1.4 Algorithm for Leasing in an Object Store

If the server implements the SMB 2.1 or SMB 3.x dialect family and supports leasing, the underlying object store needs to implement an algorithm that permits multiple opens to the same object, as described in [MS-FSA] section 2.1.5.1.2, to share the lease state (for valid lease states, see section 3.3.1.12). The algorithm MUST meet the following conditions:

• The algorithm MUST permit a create request from the server to the underlying object store to be accompanied by an implementation-specific<202> identifier that indicates the unique server-local context for this lease, which will be referred to as the ClientLeaseId.

• The algorithm MUST allow multiple opens to an object that shares the same ClientLeaseId. These opens MUST NOT alter the lease state on an object.

• The algorithm MUST permit three different caching capabilities within a lease: READ, WRITE, and HANDLE, with the following semantics:

  • READ caching permits the SMB2 client to cache data read from the object. Before processing one of the following operations from a client with a different ClientLeaseId, the object store MUST request that the server revoke READ caching. The object store is not required to wait for acknowledgment:

    READ caching on a file:

    • The file is opened in a manner that overwrites the existing file.

    • Data is written to the file.

    • The file size is changed.

    • A byte range lock is requested for the file.

      READ caching on a directory:

    • A new file or directory is added, deleted, or renamed within the directory.

    • Directory metadata such as timestamps, file attributes, and file sizes are updated.

  • WRITE caching permits the SMB2 client to cache writes and byte-range locks on an object. Before processing one of the following operations, the underlying object store MUST request that the server revoke WRITE caching, and the object store MUST wait for acknowledgment from the server before proceeding with the operation:

    • The file is opened by a client with a different ClientLeaseId, and requested access includes any flags other than FILE_READ_ATTRIBUTES, FILE_WRITE_ATTRIBUTES, and SYNCHRONIZE.

  • HANDLE caching permits one or more SMB2 clients to delay closing handles it holds open, or to defer sending opens. Before processing one of the following operations, the underlying object store MUST request that the server revoke HANDLE caching, and the object store MUST wait for acknowledgment before proceeding with the operation:

    HANDLE caching on a file:

    • A file is opened with an access or share mode incompatible with opens from clients with different ClientLeaseIds.

    • The parent directory is being renamed.

      HANDLE caching on a directory:

    • The directory is opened with an access/share mode incompatible with opens from a client with a different ClientLeaseId.

    • Parent directory is renamed or deleted.

• The underlying object store SHOULD request that the server revoke multiple lease state flags at the same time if an operation results in the loss of several caching flags.

• The algorithm SHOULD support the following combinations of caching flags on a file: No caching, Read caching, Read + Write caching, Read + Handle caching, and Read + Write + Handle caching. The algorithm SHOULD support No caching, Read caching, and Read + Handle caching on a directory.

• The algorithm MAY<203> support other combinations of caching flags.

• The algorithm MUST allow a client to flow one or more creates with the same ClientLeaseId to the underlying object store during a lease break without blocking the create until the acknowledgment of the lease break is received.

• The algorithm SHOULD allow additional lease state flags on subsequent opens with the same ClientLeaseId to permit upgrading the lease state. The algorithm MUST NOT allow the client to release lease state flags on subsequent opens with the same ClientLeaseId to downgrade the lease state.

• If the requested lease state is not a superset of the existing lease state flags for this ClientLeaseId, then the requested lease state SHOULD be interpreted as the union of the existing lease state and the requested lease state.

• When the underlying object store requests that the server issue a lease break, it MUST also provide a new lease state for the server to pass to the client as part of the lease break packet, based on the operations that caused the lease break to occur.