mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-26 15:02:52 -05:00
201 lines
10 KiB
Markdown
201 lines
10 KiB
Markdown
---
|
|
title: "Protocol changes"
|
|
date: 2022-05-17T08:46:00+01:00
|
|
weight: 30
|
|
geekdocRepo: https://github.com/owncloud/ocis
|
|
geekdocEditPath: edit/master/docs/architecture
|
|
geekdocFilePath: protocol-changes.md
|
|
---
|
|
|
|
The spaces concept allows clients to look up the space endpoints a user has access to and then do individual sync discoveries. Technically, we introduce an indirection that allows clients to rely on server provided URLs instead of hardcoded `/webdav` or `/dav/files/{username}` paths, that may change over time.
|
|
|
|
## Space discovery
|
|
|
|
{{<mermaid class="text-center">}}
|
|
%%{init: {"sequence": { "showSequenceNumbers":true, "messageFontFamily":"courier", "messageFontWeight":"normal", "messageFontSize":"11"}}}%%
|
|
%% font weight is a css bug: https://github.com/mermaid-js/mermaid/issues/1976
|
|
%% edit this diagram by pasting it into eg. https://mermaid.live
|
|
sequenceDiagram
|
|
participant Client
|
|
participant Graph
|
|
participant SpaceA
|
|
participant SpaceB
|
|
links Client: {"web": "https://owncloud.dev/clients/web/", "RClone": "https://owncloud.dev/clients/rclone/"}
|
|
link Graph: Documentation @ https://owncloud.dev/extensions/graph/
|
|
|
|
Note left of Client: First, a clients looks<br/>up the spaces a user has access to
|
|
opt space lookup
|
|
Client->>+Graph: GET /me/drives
|
|
Graph-->>-Client: 200 OK JSON list of spaces, say A, B and C,<br/> each with a dedicated webDavURL, etag and quota
|
|
end
|
|
|
|
Note left of Client: Then it can do a parallel<br/>sync discovery on spaces<br/>whose etag changed
|
|
par Client to Space A
|
|
Client->>+SpaceA: PROPFIND {webDavURL for Space A}
|
|
SpaceA-->>-Client: 207 Multistatus PROPFIND response
|
|
and Client to Space B
|
|
Client->>+SpaceB: PROPFIND {webDavURL for space B}
|
|
SpaceB-->>-Client: 207 Multistatus PROPFIND response
|
|
end
|
|
{{</mermaid>}}
|
|
|
|
### New /dav/spaces/{spaceid} endpoint with spaceid and a relative path
|
|
|
|
The ocDAV service is responsible for translating ownCloud flavoured WebDAV into CS3 API calls.
|
|
|
|
**General view**
|
|
|
|
A PROPFIND finds its way to a storage provider like this:
|
|
|
|
{{<mermaid class="text-center">}}
|
|
%%{init: {"sequence": { "showSequenceNumbers":true, "messageFontFamily":"courier", "messageFontWeight":"normal", "messageFontSize":"11"}}}%%
|
|
%% font weight is a css bug: https://github.com/mermaid-js/mermaid/issues/1976
|
|
%% edit this diagram by pasting it into eg. https://mermaid.live
|
|
sequenceDiagram
|
|
participant Client
|
|
participant ocDAV
|
|
participant StorageProvider
|
|
|
|
Note right of Client: {spaceid} identifies the space<br>{relative/path} is relative to the space root
|
|
Client->>+ocDAV: PROPFIND /dav/space/{spaceid}/{relative/path}
|
|
Note right of ocDAV: translate ownCloud flavoured webdav<br>into CS3 API requests
|
|
ocDAV->>+StorageProvider: ListContainer({spaceid}, path: {relative/path})
|
|
StorageProvider-->>-ocDAV: []ResourceInfo
|
|
ocDAV-->>-Client: 207 Multistatus
|
|
{{</mermaid>}}
|
|
|
|
While the above is a simplification to get an understanding of what needs to go where, there are several places where sharding can happen.
|
|
|
|
**Proxy can do user based routing**
|
|
|
|
The ocis proxy authenticates requests an can forward requests to different backends, depending on the logged in user or cookies. For example multiple ocdav services can be configured to shard users based on username or affiliation.
|
|
|
|
{{<mermaid class="text-center">}}
|
|
%%{init: {"sequence": { "showSequenceNumbers":true, "messageFontFamily":"courier", "messageFontWeight":"normal", "messageFontSize":"11"}}}%%
|
|
%% font weight is a css bug: https://github.com/mermaid-js/mermaid/issues/1976
|
|
%% edit this diagram by pasting it into eg. https://mermaid.live
|
|
sequenceDiagram
|
|
participant Client
|
|
participant proxy
|
|
participant ocDAV1 as ocDAV [a-k]
|
|
participant ocDAV2 as ocDAV [l-z]
|
|
|
|
Note right of Client: {spaceid} identifies the space<br>{relative/path} is relative to the space root
|
|
Client->>+proxy: PROPFIND /dav/space/{spaceid}/{relative/path}
|
|
|
|
alt username starting with a-k
|
|
proxy->>+ocDAV1: PROPFIND /dav/space/{spaceid}/{relative/path}
|
|
Note right of ocDAV1: translate ownCloud flavoured webdav<br>into CS3 API requests
|
|
ocDAV1-->>-Client: 207 Multistatus
|
|
else username starting with l-z
|
|
proxy->>+ocDAV2: PROPFIND /dav/space/{spaceid}/{relative/path}
|
|
ocDAV2-->>-Client: 207 Multistatus
|
|
end
|
|
{{</mermaid>}}
|
|
|
|
**Gateway can do path or storage provider id based routing**
|
|
|
|
The reva gateway acts as a facade to multiple storage providers that can be configured with the storage registry:
|
|
|
|
{{<mermaid class="text-center">}}
|
|
%%{init: {"sequence": { "showSequenceNumbers":true, "messageFontFamily":"courier", "messageFontWeight":"normal", "messageFontSize":"11"}}}%%
|
|
%% font weight is a css bug: https://github.com/mermaid-js/mermaid/issues/1976
|
|
%% edit this diagram by pasting it into eg. https://mermaid.live
|
|
sequenceDiagram
|
|
participant ocDAV
|
|
participant Gateway
|
|
participant StorageRegistry
|
|
participant StorageProvider1 as StoregeProvider [a-k]
|
|
participant StorageProvider2 as StoregeProvider [l-z]
|
|
|
|
Note right of ocDAV: translate ownCloud flavoured webdav<br>into CS3 API requests
|
|
ocDAV->>+Gateway: ListContainer({spaceid}, path: {relative/path})
|
|
Note right of Gateway: find address of the storage provider<br>that is responsible for the space
|
|
Gateway->>+StorageRegistry: ListStorageProviders({spaceid})
|
|
StorageRegistry-->>-Gateway: []ProviderInfo
|
|
Note right of Gateway: forward request to<br>correct storage provider
|
|
alt username starting with a-k
|
|
Gateway->>+StorageProvider1: ListContainer({spaceid}, path: {relative/path})
|
|
StorageProvider1-->>-Gateway: []ResourceInfo
|
|
else username starting with l-z
|
|
Gateway->>+StorageProvider2: ListContainer({spaceid}, path: {relative/path})
|
|
StorageProvider2-->>-Gateway: []ResourceInfo
|
|
end
|
|
Gateway-->>-ocDAV: []ResourceInfo
|
|
{{</mermaid>}}
|
|
|
|
|
|
### Old /dav/files/{username} endpoint with username and a path relative to the users home
|
|
|
|
**PROPFIND request against old webdav endpoints**
|
|
|
|
To route a PROPFIND request against the old webdav endpoints like `/dav/files/username`, ocdav first has to build a CS3 namespace prefix, eg. `/users/{{.Id.OpaqueId}}` to the users home.
|
|
|
|
{{<mermaid class="text-center">}}
|
|
%%{init: {"sequence": { "showSequenceNumbers":true, "messageFontFamily":"courier", "messageFontWeight":"normal", "messageFontSize":"11"}}}%%
|
|
%% font weight is a css bug: https://github.com/mermaid-js/mermaid/issues/1976
|
|
%% edit this diagram by pasting it into eg. https://mermaid.live
|
|
sequenceDiagram
|
|
participant Client
|
|
participant ocDAV
|
|
participant Gateway
|
|
|
|
opt old /dav/files/{username} endpoint with username and a path relative to the users home
|
|
Note right of Client: translate ownCloud flavoured webdav<br>into CS3 API requests
|
|
Client->>+ocDAV: PROPFIND /dav/files/{username}/{relative/path}
|
|
Note right of ocDAV: translate ownCloud flavoured webdav<br>into CS3 API requests
|
|
ocDAV->>+Gateway: GetUser({username})
|
|
Gateway-->>-ocDAV: User
|
|
Note right of ocDAV: build path prefix to user home
|
|
ocDAV->>+ocDAV: {namespace/prefix} = ApplyLayout({path layout}, User), eg. /users/e/einstein
|
|
Note right of ocDAV: look up the space responsible for a path
|
|
ocDAV->>+Gateway: ListStorageSpaces(path: {namespace/prefix}/{relative/path})
|
|
Gateway-->>-ocDAV: []StorageSpace
|
|
Note right of ocDAV: make actual request with space and relative path
|
|
ocDAV->>+Gateway: ListContainer({spaceid}, path: {relative/path})
|
|
Gateway-->>-ocDAV: []ResourceInfo
|
|
ocDAV-->>-Client: 207 Multistatus
|
|
end
|
|
{{</mermaid>}}
|
|
|
|
**Handling legacy global namespace webdav endpoints**
|
|
|
|
The reason ocis uses a path based lookup instead of looking up the current users home using the user id and a space type filter is, because there are deployments that use a global namespace at the legacy `/webdav` endpoint. To support these use cases, the gateway allows looking up spaces using their mount path.
|
|
|
|
{{<mermaid class="text-center">}}
|
|
%%{init: {"sequence": { "showSequenceNumbers":true, "messageFontFamily":"courier", "messageFontWeight":"normal", "messageFontSize":"11"}}}%%
|
|
%% font weight is a css bug: https://github.com/mermaid-js/mermaid/issues/1976
|
|
%% edit this diagram by pasting it into eg. https://mermaid.live
|
|
sequenceDiagram
|
|
participant Client
|
|
participant ocDAV
|
|
participant Gateway
|
|
|
|
Note right of Client: translate ownCloud flavoured webdav<br>into CS3 API requests
|
|
alt old /dav/files/{username} endpoint with username and a path relative to the users home
|
|
Client->>+ocDAV: PROPFIND /dav/files/{username}/{relative/path}
|
|
Note right of ocDAV: look up {username} in URL path
|
|
ocDAV->>+Gateway: GetUser({username})
|
|
Gateway-->>-ocDAV: User
|
|
Note right of ocDAV:build namespace prefix to user home
|
|
ocDAV->>+ocDAV: {namespace/prefix} = ApplyLayout({namespace layout}, User), eg. /users/e/einstein
|
|
else legacy /webdav/ endpoint with a path relative to the users home
|
|
Client->>+ocDAV: PROPFIND /webdav/{relative/path}
|
|
Note right of ocDAV: use currently logged in user
|
|
ocDAV->>+ocDAV: ContextGetUser()
|
|
Note right of ocDAV: build namespace prefix to user home
|
|
ocDAV->>+ocDAV: {namespace/prefix} = ApplyLayout({namespace layout}, User), eg. /users/e/einstein
|
|
else legacy /webdav/ endpoint with a path relative to a global namespace
|
|
Client->>+ocDAV: PROPFIND /webdav/{relative/path}
|
|
Note right of ocDAV: omit namespace prefix by using empty layout template
|
|
ocDAV->>+ocDAV: {namespace/prefix} = ApplyLayout("/", u), always returns "/"
|
|
end
|
|
Note right of ocDAV: look up the space responsible for a path
|
|
ocDAV->>+Gateway: ListStorageSpaces(path: {namespace/prefix}/{relative/path})
|
|
Gateway-->>-ocDAV: []StorageSpace
|
|
Note right of ocDAV: make actual request with space and relative path
|
|
ocDAV->>+Gateway: ListContainer({spaceid}, path: {relative/path})
|
|
Gateway-->>-ocDAV: []ResourceInfo
|
|
ocDAV-->>-Client: 207 Multistatus
|
|
{{</mermaid>}}
|