mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-01 09:52:23 -06: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 and 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 StorageProvider [a-k]
|
|
participant StorageProvider2 as StorageProvider [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, e.g. `/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>}}
|