Lock request: X-WOPI-Lock might not be returned with 409

[mikekaganski]

docs/rest/src/files/Lock.rst tells:

X-WOPI-Lock – A string value identifying the current lock on the file. This header must always be included when responding to the request with 409 Conflict.

However, this contradicts [MS-WOPI] v20190618 3.3.5.1.14, which tells:

X-WOPI-Lock ... This header SHOULD be included when responding with the 409 status code if a different shared lock exists on the file.

(emphasis mine in both quotes)

And actually, if a LOCK request is sent to a checked-out file on a SharePoint server, the response 409 includes X-WOPI-LockFailureReason: ExistingCheckout, X-WOPI-LockedByOtherInterface: true, but no X-WOPI-Lock.

[tylerbutler]

The documentation contained here is intended for those who are implementing integration with Office on the web. It doesn’t have anything to do with SharePoint.

WOPI hosts integrating with Office on the web must always include a lock header on responses.

[mikekaganski]

Wow. Fantastic. "The documentation here contradicts the published protocol standard, and contradicts the "reference" implementation of the host by MS (which is intended for integration with OWA/Office on the web). WOPI hosts other than MS must follow the rules other than MS."

[tylerbutler]

@mikekaganski That is not what I said. Please don’t put words in my mouth.

Can you please clarify what you’re referring to when you write “reference server?”

Also, if I understand correctly, a host that always returns a X-WOPI-Lock header on a 409 response is valid per the SHOULD RFC wording in MS-WOPI. However, it’s possible that I am misunderstanding. If so please clarify the contradictions.

Finally, this documentation is also not related to Office Online Server, the on-premise version of Office for the web. It is very specific in its purpose: to guide WOPI implementations for integration with Office for the web and Office mobile as part of the Cloud Storage Partner Program.

[mikekaganski]

SHOULD, per RFC 2119, as well as "RECOMMENDED", means "that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course".

But the protocol specification mentioned initially not only uses this word, that is not the same as "must always"; it goes on, and tells when exactly the header SHOULD appear: it only is RECOMMENDED if a different shared lock exists on the file. What does that mean in practice? There may be valid cases when there is a conflict that prevents the Lock request, but where there is no different shared lock exist that may be returned here. I realize that Office on the web is a bit different, but that doesn't change anything in my example: SharePoint provides a WOPI host implementation, and it shows a valid sample of that situation. Another host - e.g. targeting Office on the web - might also have a similar situation.

Additionally, creating a documentation on a protocol that has its standard, which (the documentation) differs from the standard in details, in fact creates a competing version of the protocol; creates uncertainty in the ecosystem that uses that protocol. That is not good, and has precedents in the history, that made some bad results e.g. for HTML for a long time. The difference must be either put into the standard (of course, it needs some reason for that), or be fixed (made to follow the standard).