Various grammar and typos
This commit is contained in:
Phil Davis
@@ -36,7 +36,7 @@ Chosen option: "GLAuth wraps accounts service", because we need write access to
|
||||
|
||||
### Positive Consequences
|
||||
|
||||
* We can build a self contained user management in the accounts service and can adjust it to our requirements.
|
||||
* We can build a self-contained user management in the accounts service and can adjust it to our requirements.
|
||||
* We do not rely on an LDAP server which would only be possible by implementing write support in the LDAP libraries used by GLAuth (hard to estimate effort, when will that be merged upstream).
|
||||
|
||||
### Negative Consequences
|
||||
|
||||
@@ -19,7 +19,7 @@ Migration is one of the most important topics of the oCIS story. We need to prov
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
- Do not lose file blob or meta data.
|
||||
- Do not lose file blob or metadata.
|
||||
- To prevent a sync surge from clients the etag for files should be migrated.
|
||||
- To prevent internal links from breaking or pointing to wrong files the file id of existing files needs to be migrated.
|
||||
- To prevent data loss trash and version blobs should be migrated.
|
||||
@@ -27,7 +27,7 @@ Migration is one of the most important topics of the oCIS story. We need to prov
|
||||
- To prevent internal shares the share type, permissions and expiry needs to be migrated.
|
||||
- To prevent public links from breaking the url token, permissions, expiry and password needs to be migrated.
|
||||
- *What about federated shares?*
|
||||
- *What about additional share permissions, eg. comment on office files?*
|
||||
- *What about additional share permissions, e.g. comment on office files?*
|
||||
- Legacy clients need to keep working
|
||||
- To keep existing clients working the `remote.php/webdav` and `dav/files/<username>` webdav endpoints as well as the ocs API need to be available.
|
||||
- *What about [app passwords/tokens](https://doc.owncloud.com/server/user_manual/personal_settings/security.html#app-passwords-tokens)?*
|
||||
@@ -55,7 +55,7 @@ Chosen option: "\[option 1\]", because \[justification. e.g., only option, which
|
||||
|
||||
### Cold Migration
|
||||
|
||||
The migration happens while the service is offline. File metadata, blobs and share data is exported from ownCloud 10 and imported in oCIS. This can happen user by user, where every user export would contain the file blobs, their metadata, trash, versions, shares and all metadata that belongs to the users storage. To prevent group shares from breaking, users in the same groups must be migrated in batch. Depending on the actual group shares in an instance this may effectively require a complete migration in a single batch.
|
||||
The migration happens while the service is offline. File metadata, blobs and share data is exported from ownCloud 10 and imported in oCIS. This can happen user by user, where every user export would contain the file blobs, their metadata, trash, versions, shares and all metadata that belongs to the users storage. To prevent group shares from breaking, users in the same groups must be migrated in batch. Depending on the actual group shares in an instance this may effectively require a complete migration in a single batch.
|
||||
|
||||
- Good, because oCIS can be tested in a staging system without writing to the production system.
|
||||
- Good, because file layout on disk can be changed to support new storage driver capabilities.
|
||||
@@ -76,5 +76,5 @@ The migration happens in subsequent stages while the service is online.
|
||||
|
||||
## Links
|
||||
|
||||
|
||||
- [Clarify responsibilities of share providers and storage providers · Issue #1377 · cs3org/reva (github.com)](https://github.com/cs3org/reva/issues/1377) because the share manager for oCIS should store share information on the storage system. And [storageprovider should persist share creator · Issue #93 · cs3org/cs3apis (github.com)](https://github.com/cs3org/cs3apis/issues/93) finally: [eos: store share id in inherited xattr · Issue #543 · cs3org/reva (github.com)](https://github.com/cs3org/reva/issues/543)
|
||||
|
||||
- [Clarify responsibilities of share providers and storage providers · Issue #1377 · cs3org/reva (github.com)](https://github.com/cs3org/reva/issues/1377) because the share manager for oCIS should store share information on the storage system. And [storage provider should persist share creator · Issue #93 · cs3org/cs3apis (github.com)](https://github.com/cs3org/cs3apis/issues/93) finally: [eos: store share id in inherited xattr · Issue #543 · cs3org/reva (github.com)](https://github.com/cs3org/reva/issues/543)
|
||||
|
||||
@@ -155,7 +155,7 @@ Creating an account using the first option looks currently is implemented in ven
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
As explained before, during this flow no Reva middlewares are ran. Creating an account will only use the embedded accounts js file alongside a minted jwt token (by the oCIS proxy) to communicate with the accounts service.
|
||||
As explained before, during this flow no Reva middlewares are run. Creating an account will only use the embedded accounts js file alongside a minted jwt token (by the oCIS proxy) to communicate with the accounts service.
|
||||
|
||||
### Add account management to the CS3 API
|
||||
|
||||
|
||||
@@ -151,6 +151,6 @@ Meaningful fields of the root element in the context of the Open Graph API:
|
||||
|
||||
### Open Topics
|
||||
|
||||
- What are the WebDAV pathes for Trashbin, Versions
|
||||
- What are the WebDAV paths for Trashbin, Versions
|
||||
+ option: additional entries in the reply struct
|
||||
- The identitySet object used for "owner" and "coowner" require to implement the [https://docs.microsoft.com/de-de/graph/api/resources/identityset?view=graph-rest-1.0](IdentitySet) JSON object, which contains information that seems to be of limited benefit for oCIS. An alternative would be to implement a simpler identity object for oCIS and use that.
|
||||
|
||||
@@ -66,6 +66,6 @@ Create a git repository with an extension containing the boilerplate code.
|
||||
We have the ocis-hello repository which acts as an example extension containing a grpc and http service and a web UI. It also demonstrates the usage of the settings service.
|
||||
|
||||
* Good, because it contains a bit more code than just the plain boilerplate
|
||||
* Good, because the integration into oCIS is already tested for the Hello extension (eg. with Proxy and Settings). This will ensure, that the example extension is up to date.
|
||||
* Good, because the integration into oCIS is already tested for the Hello extension (e.g. with Proxy and Settings). This will ensure, that the example extension is up-to-date.
|
||||
* Bad, because if you don't require all features you have to delete stuff
|
||||
|
||||
|
||||
@@ -49,7 +49,7 @@ Chosen option: option 2; Use third party libraries such as Open Policy Agent (a
|
||||
|
||||
## Chosen option approach
|
||||
|
||||
Make use of [overloading Open Policy Agent's input](https://www.openpolicyagent.org/docs/latest/external-data/#option-2-overload-input) along with an external storage source (instead of an OPA service) in conjunction with go-micro's gRPC client wrappers (a.k.a middlewares) to leverage policy rules evaluation.
|
||||
Make use of [overloading Open Policy Agent's input](https://www.openpolicyagent.org/docs/latest/external-data/#option-2-overload-input) along with an external storage source (instead of an OPA service) in conjunction with go-micro's gRPC client wrappers (a.k.a. middlewares) to leverage policy rules evaluation.
|
||||
|
||||
### Terminology
|
||||
|
||||
@@ -68,7 +68,7 @@ New terms are defined to refer to new mental models:
|
||||
|
||||
However, for this to be usable it needs state. The Rego engine works with input and data, where data is essentially a database the input is tried against, in order to expand this poc to include functionality such as counters (i.e: give access to the thumbnails only to 50 users) we need an external storage, and consequentially, Rego needs to have an option to load data from an external storage. There is an entire chapter in the documentation regarding external data: https://www.openpolicyagent.org/docs/latest/external-data/. The most "natural" option (option 5) states:
|
||||
|
||||
> OPA includes functionality for reaching out to external servers during evaluation. This functionality handles those cases where there is too much data to synchronize into OPA, JWTs are ineffective, or policy requires information that must be as up to date as possible.
|
||||
> OPA includes functionality for reaching out to external servers during evaluation. This functionality handles those cases where there is too much data to synchronize into OPA, JWTs are ineffective, or policy requires information that must be as up-to-date as possible.
|
||||
|
||||
This is a natural option because it requires service-to-service communication, and by definition using microservices it should come "natural to us". Another approach is using JWT (which we already use) to encode the necessary data into the JWT and handing it over to rego as "data". The issue with this approach is that depending on the features of the licenses the JWT might grow and be filled with noise and redundancy (this is, unless a new token is issued for licensing purposes).
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ When the URL contains a `fileid` parameter the server will look up the correspon
|
||||
GET https://demo.owncloud.com/apps/files/?dir=/path/to/resource
|
||||
```
|
||||
|
||||
The `dir` parameter is then used to make a WebDAV request against the `/dav/files` endpoint of the currently logged in user:
|
||||
The `dir` parameter is then used to make a WebDAV request against the `/dav/files` endpoint of the currently logged-in user:
|
||||
|
||||
```
|
||||
PROPFIND https://demo.owncloud.com/remote.php/dav/files/demo/path/to/resource
|
||||
@@ -42,7 +42,7 @@ https://demo.owncloud.com/#/files/list/all/path/to/resource
|
||||
|
||||
Currently, there is no `fileid` like parameter in the browser URL, making bookmarks of it fragile (they break when a bookmarked folder is renamed).
|
||||
|
||||
The oCIS web UI just takes the path and uses the `/webdav` endpoint of the currently logged in user:
|
||||
The oCIS web UI just takes the path and uses the `/webdav` endpoint of the currently logged-in user:
|
||||
|
||||
```
|
||||
PROPFIND https://demo.owncloud.com/remote.php/webdav/path/to/resource
|
||||
@@ -78,7 +78,7 @@ This ADR is limited to the scope of "how will a web client deal with the browser
|
||||
|
||||
|
||||
{{< hint >}}
|
||||
@jfd: The graph api returns a `path` in the `parentReference`, which is part of the `root` in a `drive` resource. But it contains a value in the namespace of the `graph` endpoint, eg.: `/drive/root:/Bilder` for the `/Bilder` folder in the root of the currently logged in users personal drive/space. Which is again relative to the drive. To give the clients a way to determine the mount point we need to add a new `mountpath/point/alias` property.
|
||||
@jfd: The graph api returns a `path` in the `parentReference`, which is part of the `root` in a `drive` resource. But it contains a value in the namespace of the `graph` endpoint, e.g.: `/drive/root:/Bilder` for the `/Bilder` folder in the root of the currently logged-in users personal drive/space. Which is again relative to the drive. To give the clients a way to determine the mount point we need to add a new `mountpath/point/alias` property.
|
||||
{{< /hint >}}
|
||||
|
||||
## Decision Drivers
|
||||
@@ -130,7 +130,7 @@ It contains a path and a `fileid` (which takes precedence).
|
||||
* Bad, because URLs still contain a long prefix `(/index.php)/apps/files`
|
||||
* Bad, because the `fileid` needs to be accompanied by a `storageid` to allow efficient routing in ocis
|
||||
* Bad, because if not configured properly an additional `/index.php` prefixes the route
|
||||
* Bad, because powerusers cannot navigate by updating only the path in the URL, as the `fileid` takes precedence. They have to delete the `fileid` to navigate
|
||||
* Bad, because power users cannot navigate by updating only the path in the URL, as the `fileid` takes precedence. They have to delete the `fileid` to navigate
|
||||
|
||||
### ID based URLs
|
||||
|
||||
@@ -160,7 +160,7 @@ There is a customized ownCloud instance that uses path only based URLs:
|
||||
| `https://demo.owncloud.com/apps/files/?dir=/path/to/resource&` | sub folder `/path/to/resource` |
|
||||
|
||||
* Good, because the URLs reveal the full path context to users
|
||||
* Good, because powerusers can navigate by updating the path in the url
|
||||
* Good, because power users can navigate by updating the path in the url
|
||||
* Bad, because the web UI needs to look up the space id in a registry to build an API request for the `/dav/space` endpoint
|
||||
* Bad, because the bookmarks break when someone renames a folder in the path
|
||||
* Bad, because there is no id that can be used as a fallback lookup mechanism
|
||||
@@ -185,7 +185,7 @@ There is a customized ownCloud instance that uses path only based URLs:
|
||||
* Good, because the web UI does not need to look up the space id in a registry to build an API request for the `/dav/space` endpoint
|
||||
* Good, because the URLs reveal a relevant path context to users
|
||||
* Good, because everything after the `#` is not sent to the server, building the webdav request to list the folder is offloaded to the clients
|
||||
* Good, because powerusers can navigate by updating the path in the url
|
||||
* Good, because power users can navigate by updating the path in the url
|
||||
* Bad, because the current ids are uuid based, leading to very long URLs where the path component nearly vanishes between two very long strings
|
||||
* Bad, because the `#` in the URL is just a technical requirement
|
||||
* Bad, because ocis web requires a `/#/files/s` at the root of the route to distinguish the files app from other apps
|
||||
@@ -266,14 +266,14 @@ In order to be able to copy and paste URLs all resources must be uniquely identi
|
||||
* An url shortener can create urls like `/s/<token>` which could be used as a stable link to a resource.
|
||||
* Links for anonymous users will resolve to `/public/<token>`
|
||||
|
||||
The alias namespace hierarchy and depth can be pre determined by the admin. Even if aliases change the `id` parameter prevents bookmarks from breaking. A user can decide to build a different hierarchy by using his own registry.
|
||||
The alias namespace hierarchy and depth can be pre-determined by the admin. Even if aliases change the `id` parameter prevents bookmarks from breaking. A user can decide to build a different hierarchy by using his own registry.
|
||||
|
||||
What about shares? Similar to `/home` it must reflect the user: `/shares/einstein` would list all shares *by* einstein for the currently logged in user. The ui needs to apply the same URL rewriting as for space based URLs: when navigating into a share the URL has to switch from `/personal/einstein/relative/path/to/shared/resource` to `/shares/einstein/<unique and potentially namespaced alias for shared resource>`. When more than one `resource` was shared a name collision would occur. To prevent this we can use ids `/shares/einstein/id/<resource_id` or namespaced aliases `/shares/einstein/files/alias`. Similar to the `/trash` prefix we could treat `/shares` as a filter for the shared resources a user has access to, but that would disclose unshared path segments in personal spaces. We could make that a feature and let users create an alias for a shared resource, similar as for public links. Then they can decide if they want to disclose the full path in their personal space (or another workspace) or if they want to use an alias which is then accessed at `/shares/einstein/<alias>`. As a default we could take the alias at creation time from the filename. That way two shares to a resource with the same name, eg.: `/personal/einstein/project AAA/foo` and `/personal/einstein/project BBB/foo` would lead to `/shares/einstein/foo` (a CS3 internal reference to `/personal/einstein/project AAA/foo`) and `/shares/einstein/foo (2)` (a CS3 internal reference to `/personal/einstein/project BBB/foo`). `foo (2)` would keep its name even when `foo` is deleted or renamed. Well an id as the alias might be better then, because users might rename these aliases, which would break URLs if they have been bookmarked. In any case this would make end user more aware of what they share AND it would allow them to choose an arbitrary context for the links they want to send out: personal internal share URLs.
|
||||
What about shares? Similar to `/home` it must reflect the user: `/shares/einstein` would list all shares *by* einstein for the currently logged-in user. The ui needs to apply the same URL rewriting as for space based URLs: when navigating into a share the URL has to switch from `/personal/einstein/relative/path/to/shared/resource` to `/shares/einstein/<unique and potentially namespaced alias for shared resource>`. When more than one `resource` was shared a name collision would occur. To prevent this we can use ids `/shares/einstein/id/<resource_id` or namespaced aliases `/shares/einstein/files/alias`. Similar to the `/trash` prefix we could treat `/shares` as a filter for the shared resources a user has access to, but that would disclose unshared path segments in personal spaces. We could make that a feature and let users create an alias for a shared resource, similar as for public links. Then they can decide if they want to disclose the full path in their personal space (or another workspace) or if they want to use an alias which is then accessed at `/shares/einstein/<alias>`. As a default we could take the alias at creation time from the filename. That way two shares to a resource with the same name, e.g.: `/personal/einstein/project AAA/foo` and `/personal/einstein/project BBB/foo` would lead to `/shares/einstein/foo` (a CS3 internal reference to `/personal/einstein/project AAA/foo`) and `/shares/einstein/foo (2)` (a CS3 internal reference to `/personal/einstein/project BBB/foo`). `foo (2)` would keep its name even when `foo` is deleted or renamed. Well an id as the alias might be better then, because users might rename these aliases, which would break URLs if they have been bookmarked. In any case this would make end user more aware of what they share AND it would allow them to choose an arbitrary context for the links they want to send out: personal internal share URLs.
|
||||
|
||||
With these different namespaces the `/files` part in the URL becomes obsolete, because the files application can be registered for multiple namespaces: `/personal`, `/workspaces`, `/shares`, `/trash` ...
|
||||
|
||||
* Good, because it contains a global path
|
||||
* Good, because spaces with namespaced aliases can by bookmarked and copied into mails or chat without disclosing unshared path segments, as the space is supposed to be shared
|
||||
* Good, because spaces with namespaced aliases can be bookmarked and copied into mails or chat without disclosing unshared path segments, as the space is supposed to be shared
|
||||
* Good, because the UI can detect broken paths and notify the user to update his bookmark if the resource could be found by `id`
|
||||
* Good, because the `/files` part might only be required for `id` only based lookup to let the web ui know which app is responsible for the route
|
||||
* Good, because it turns shares into deliberately named spaces in `/shares/<owner>/<alias>`
|
||||
@@ -297,7 +297,7 @@ When a file is selected the filename also becomes part of the URL so individual
|
||||
|
||||
If navigation is id based we need to look up the path for the id so we can make a webdav request, or we need to implement the graph drives and driveItem resources.
|
||||
|
||||
The URL `https://<host>/files?id=<resource_id>̀` is sent to the server. It has to look up the correct path and redirect the request, including the the path. But that would make all bookmarks contain tha path again, even if paths were configured to not be part of the URL.
|
||||
The URL `https://<host>/files?id=<resource_id>̀` is sent to the server. It has to look up the correct path and redirect the request, including the path. But that would make all bookmarks contain tha path again, even if paths were configured to not be part of the URL.
|
||||
|
||||
The `/meta/<fileid>` webdav endpoint can be used to look up the path with property `meta-path-for-user`.
|
||||
|
||||
@@ -307,7 +307,7 @@ For now, we would use path based navigation with URLs like this:
|
||||
https://<host>/files</namespaced/alias></relative/path/to/resource>?id=<resource_id>
|
||||
```
|
||||
|
||||
This means that only the _resource path_ is part of the URL path. Any other parameter, eg. file `id`, `page` or sort order must be given as URL parameters.
|
||||
This means that only the _resource path_ is part of the URL path. Any other parameter, e.g. file `id`, `page` or sort order must be given as URL parameters.
|
||||
|
||||
- [ ] To make lookup by id possible we need to implement the `/meta/<fileid>` endpoint so the sdk can use it to look up the path. We should not implement a redirect on the ocis server side because the same redirect logic would need to be added to oc10. Having it in ocis web is the right place.
|
||||
|
||||
@@ -316,5 +316,5 @@ This means that only the _resource path_ is part of the URL path. Any other para
|
||||
Public links would have the same format: `https://<host>/files?id=<resource_id>` The web UI has to detect if the user is logged in or not and adjust the ui accordingly.
|
||||
|
||||
{{< hint warning >}}
|
||||
Since there is no difference between public and private files a logged in user cannot see the public version of a link unless he logs out.
|
||||
Since there is no difference between public and private files a logged-in user cannot see the public version of a link unless he logs out.
|
||||
{{< /hint >}}
|
||||
|
||||
@@ -46,4 +46,4 @@ Chosen option: option 3; Migrate to OpenTelemetry. OpenCensus is deprecated, and
|
||||
- The unit that ultimately does the work will change the state of the span to error if any occurred.
|
||||
|
||||
|
||||
With this premises, this is by no means a fixed document and the more we learn about the usage of an instance the more context we can add to the traces.
|
||||
With these premises, this is by no means a fixed document and the more we learn about the usage of an instance the more context we can add to the traces.
|
||||
|
||||
@@ -44,15 +44,15 @@ The CS3org WOPI server creates a `.sys.wopilock.<filename>.` and `.~lock.<filena
|
||||
|
||||
**File based locking is bad**, because:
|
||||
|
||||
- lock files should be checked by all partys manipulating files (eg. the WebDAV api)
|
||||
- lock files should be checked by all parties manipulating files (e.g. the WebDAV api)
|
||||
- lock files can be deleted by everyone
|
||||
- you can not lock files in a file-only share (you need a folder share to create a lock file besides the original file)
|
||||
|
||||
If we have file based locks, we can also sync them with eg. the Desktop Client.
|
||||
If we have file based locks, we can also sync them with e.g. the Desktop Client.
|
||||
|
||||
**Syncing lock files is good**: because
|
||||
|
||||
- native office applications can notice lock files by the WOPI server and vice versa (Libre Office also creates `.lock.<filename>#` files)
|
||||
- native office applications can notice lock files by the WOPI server and vice versa (LibreOffice also creates `.lock.<filename>#` files)
|
||||
|
||||
**Syncing lock files is bad**, because:
|
||||
|
||||
@@ -70,7 +70,7 @@ We remove or disable the file based locking of the CS3org WOPI server.
|
||||
|
||||
**No locking is bad**, because:
|
||||
|
||||
- merging changes from different versions is a pain, since there is no way to calculate differences for most of the files (eg. docx or xlsx files)
|
||||
- merging changes from different versions is a pain, since there is no way to calculate differences for most of the files (e.g. docx or xlsx files)
|
||||
- no locking breaks the WOPI specs, as the CS3 WOPI server won't be capable to honor the WOPI Lock related operations
|
||||
|
||||
### CS3 API locking
|
||||
@@ -78,7 +78,7 @@ We remove or disable the file based locking of the CS3org WOPI server.
|
||||
- Add CS3 API for resource (files, directories) locking, unlocking and checking locks
|
||||
- locking always with timeout
|
||||
- lock creation is a "create-if-not-exists" operation
|
||||
- locks need to have arbitrary metadata (eg. the CS3 WOPI server is stateless by storing information on / in the locks)
|
||||
- locks need to have arbitrary metadata (e.g. the CS3 WOPI server is stateless by storing information on / in the locks)
|
||||
- Implement WebDAV locking using the CS3 API
|
||||
- Implement Locking in storage drivers
|
||||
- Change CS3 WOPI server to use CS3 API locking mechanism
|
||||
@@ -89,7 +89,7 @@ We remove or disable the file based locking of the CS3org WOPI server.
|
||||
- you can lock files on the actual storage (if the storage supports that -> storage driver dependent)
|
||||
- you can lock files in ownCloud 10 when using the ownCloudSQL storage driver in the migration deployment (but oC10 Collabora / OnlyOffice also need to implement locking, to fully leverage that)
|
||||
- clients can get the lock information via the api without ignoring / hiding lock file changes
|
||||
- clients can use the lock information to lock the file in their context (eg. via some file explorer integration)
|
||||
- clients can use the lock information to lock the file in their context (e.g. via some file explorer integration)
|
||||
|
||||
**CS3 API locking is bad**, because:
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ To be able to implement simple, flexible and independent inter service communica
|
||||
|
||||
### Example: Email Notification
|
||||
|
||||
A simple example is the notification feature for oCIS: Users should receive an email when another user shares a file with them. The information, that the file was shared should go out as an event from a storage provider or share manager, carrying the information which file was shared to which receiver. A potential notification service that sends out the email listens to these kind of events and sends the email out once on every received event of that specific type.
|
||||
A simple example is the notification feature for oCIS: Users should receive an email when another user shares a file with them. The information, that the file was shared should go out as an event from a storage provider or share manager, carrying the information which file was shared to which receiver. A potential notification service that sends out the email listens to these kinds of events and sends the email out once on every received event of that specific type.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
@@ -40,17 +40,17 @@ A simple example is the notification feature for oCIS: Users should receive an e
|
||||
|
||||
Reva will get a messaging service that is available to all services within oCIS and Reva. It is considered as one of the mandatory services of the oCIS system. If the messaging backend is not running, neither Reva nor oCIS can be considered healthy and should shut down.
|
||||
|
||||
All oCIS- and Reva-services can connect to the messaging bus and send so called events. The sender gets an immediate return if handing the event to the message bus was succesful or not.
|
||||
All oCIS- and Reva-services can connect to the messaging bus and send so-called events. The sender gets an immediate return if handing the event to the message bus was successful or not.
|
||||
|
||||
The sender can not make any assumptions when the message is delivered to any receiving service. Depending on the QoS model (as proposed as alternatives in this ADR) it might even be not guaranteed that the event is delivered at all. Also, the sender can not know if zero, one or many services are listening to that event.
|
||||
|
||||
#### Event Data
|
||||
|
||||
Events are identified by their namespace and their respective name. The namespace is delimited by dots and starts with either "reva" or "ocis" or an future extension name. It is followed by the name of the sending service and an unique name of the event.
|
||||
Events are identified by their namespace and their respective name. The namespace is delimited by dots and starts with either "reva" or "ocis" or a future extension name. It is followed by the name of the sending service and an unique name of the event.
|
||||
|
||||
Example: `ocis.ocdav.delete` - an event with that name sent out if an WebDAV DELETE request arrived in the oCDav service.
|
||||
|
||||
An event can carry a payload which is encoded as json object. (See for example [NATS](https://docs.nats.io/using-nats/developer/sending/structure) ). There are no pre defined members in that object, it is fully up to the sender which data will be included in the payload. Receivers must be robust to deal with changes.
|
||||
An event can carry a payload which is encoded as json object. (See for example [NATS](https://docs.nats.io/using-nats/developer/sending/structure) ). There are no pre-defined members in that object, it is fully up to the sender which data will be included in the payload. Receivers must be robust to deal with changes.
|
||||
|
||||
#### Quality of Service
|
||||
|
||||
@@ -82,7 +82,7 @@ Exactly as described above, but with a higher service level quality.
|
||||
|
||||
#### Quality of Service
|
||||
|
||||
Events are sent with "At least once" quality of service. That means the events will remain in the queue until they are received by all receivers. This puts more responsability on the event bus and adds state to the events. Given that the event queue can be considered the backbone of the system, it is required to be running.
|
||||
Events are sent with "At least once" quality of service. That means the events will remain in the queue until they are received by all receivers. This puts more responsibility on the event bus and adds state to the events. Given that the event queue can be considered the backbone of the system, it is required to be running.
|
||||
|
||||
#### Pros
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ geekdocFilePath: 0017-allow-read-only-external-user-management.md
|
||||
oCIS needs to be integrated with various external Authentication and Identity Management Systems.
|
||||
Usually oCIS will have no administrative access to such a system and we will not be allowed to
|
||||
reconfigure it to suit our needs (e.g. we will not be able to enhance the schema of an already existing
|
||||
LDAP Directory). In most of the cases our access will be read-only.
|
||||
LDAP Directory). In most of the cases our access will be read-only.
|
||||
|
||||
Sidenote: There is a difference between users, identities and accounts: A user may have multiple
|
||||
identities which he can authenticate with, e.g. his facebook, twitter, microsoft or google
|
||||
@@ -27,8 +27,8 @@ provider to another.
|
||||
There are different cases where oCIS requires access to users:
|
||||
|
||||
1. While we settled on using OpenID Connect (OIDC) as the authentication protocol for oCIS, we
|
||||
we need to build a user object during authentication with at least an account UUID (to identify
|
||||
the account) and the email or a name (for display purposes).
|
||||
need to build a user object during authentication with at least an account UUID (to identify
|
||||
the account) and the email or a name (for display purposes).
|
||||
2. When searching for share recipients we need to be able to query existing users in the external
|
||||
identity management system
|
||||
3. When listing files we need to be able to look up a users display properties (username, email,
|
||||
@@ -49,7 +49,7 @@ of stable identifier for users:
|
||||
* oCIS should be a single binary that can run out of the box without external dependencies like an
|
||||
LDAP server.
|
||||
* Time: we want to build a release candidate asap.
|
||||
* oCIS should be easy to integrate with standard external identity mangement systems
|
||||
* oCIS should be easy to integrate with standard external identity management systems
|
||||
|
||||
## Considered Options
|
||||
|
||||
@@ -73,7 +73,7 @@ to support both scenarios.
|
||||
|
||||
## Pros and Cons of the Options <!-- optional -->
|
||||
|
||||
### External identity management system is read only and provides an interface to query users (e.g. Coporate Active Directy)
|
||||
### External identity management system is read only and provides an interface to query users (e.g. Corporate Active Directory)
|
||||
|
||||
IdP sends sub & iss and mail or username claims, Identity Management System provides APIs (e.g.
|
||||
LDAP, SCIM, REST ...) to lookup additional user information. All oCIS services use the CS3 API to
|
||||
@@ -82,20 +82,20 @@ the APIs provided by the IdM.
|
||||
|
||||
* Good, because we can rely on the external identity management
|
||||
* Good, because ocis services only need to know about the CS3 user provider API, which acts as an
|
||||
abstraction layer for different identitiy management systems
|
||||
abstraction layer for different identity management systems
|
||||
* Good, because there is only a single source of truth (the external IdM) and we don't need to
|
||||
implement a synchronization mechanism to maintain an internal user database (we will likely need
|
||||
some form of caching though, see below)
|
||||
* Bad, because the identity managment needs to provide a stable, persistent, non-reassignable user
|
||||
* Bad, because the identity management needs to provide a stable, persistent, non-reassignable user
|
||||
identifier for an account, e.g. `owncloudUUID` or `ms-DS-ConsistencyGuid`
|
||||
* Bad, because we need to implment tools that can change the account id when it did change anyway
|
||||
* Bad, because we need to implement tools that can change the account id when it did change anyway
|
||||
* Bad, because without caching we will hammer the identity management system with lookup requests
|
||||
|
||||
### External identity management system is read only and does NOT provide an API to query users
|
||||
|
||||
Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping,
|
||||
creating a unique ID, upon the first login of a user to be able to look up user properties by account
|
||||
id.
|
||||
id.
|
||||
|
||||
* Good, because this has very little external requirements
|
||||
* Good, because we have accounts fully under our control
|
||||
|
||||
@@ -29,7 +29,7 @@ Sharing adds more complexity because the index also needs to react to create, de
|
||||
* Be able to construct intelligent searches based on metadata
|
||||
* Allow the user to filter the search queries based on metadata
|
||||
* Basic File Search needs to be implemented out of the box without external dependencies
|
||||
* The Search Indexing Service should be replacable with more sophisticated technologies like Elasticsearch
|
||||
* The Search Indexing Service should be replaceable with more sophisticated technologies like Elasticsearch
|
||||
* Make use of the spaces architecture to shard search indexes by space
|
||||
* The Search Indexing Service needs to deal with multiple users accessing the same resources due to shares
|
||||
* The Search Service should be compatible with different search indexing technologies
|
||||
|
||||
@@ -13,18 +13,18 @@ geekdocFilePath: 0018-file-search-query-language.md
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
From the users perspective, the interface to search is just a single form field where the user enters one or more search terms. The minimum expectation is that the search returns file names and links to files that
|
||||
From the users perspective, the interface to search is just a single form field where the user enters one or more search terms. The minimum expectation is that the search returns file names and links to files that:
|
||||
|
||||
* have a file name that contains at least one of the search terms
|
||||
* contain at least one of the search terms in the file contents
|
||||
* have meta data that is equal or contains one of the search terms
|
||||
* have metadata that is equal or contains one of the search terms
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
* The standard user should not be bothered by a query syntax
|
||||
* The power user should also be able to narrow his search with an efficient and flexible syntax
|
||||
* We need to consider different backend technologies which we need to access through an abstraction layer
|
||||
* Using different indexing systems should lead to a slightly different feature set whitout changing the syntax completely
|
||||
* Using different indexing systems should lead to a slightly different feature set without changing the syntax completely
|
||||
|
||||
## Considered Options
|
||||
|
||||
@@ -65,16 +65,16 @@ The Lucene Query Parser syntax supports advanced queries like term, phrase, wild
|
||||
* Good, because it is a well documented and powerful syntax
|
||||
* Good, because it is very close to the Elasticsearch and the Solr syntax which enhances compatibility
|
||||
* Bad, because there is no powerful and well tested query parser for golang available
|
||||
* Bad, because it adds complexity and fulfilling all the different query usecases can be an "uphill battle"
|
||||
* Bad, because it adds complexity and fulfilling all the different query use-cases can be an "uphill battle"
|
||||
|
||||
### Solr Query Language
|
||||
|
||||
Solr is highly reliable, scalable and fault tolerant, providing distributed indexing, replication and load-balanced querying, automated failover and recovery, centralized configuration and more. Solr powers the search and navigation features of many of the world's largest internet sites.
|
||||
Solr is highly reliable, scalable and fault-tolerant, providing distributed indexing, replication and load-balanced querying, automated failover and recovery, centralized configuration and more. Solr powers the search and navigation features of many of the world's largest internet sites.
|
||||
|
||||
* Good, because it is a well documented and powerful syntax
|
||||
* Good, because it is very close to the Elasticsearch and the Lucene syntax which enhances compatibility
|
||||
* Good, because it has a strong community with large resources and knowledge
|
||||
* Bad, because it adds complexity and fulfilling all the different query usecases can be an "uphill battle"
|
||||
* Bad, because it adds complexity and fulfilling all the different query use-cases can be an "uphill battle"
|
||||
|
||||
### Elasticsearch Query Language
|
||||
|
||||
@@ -83,8 +83,8 @@ Elasticsearch provides a full Query DSL (Domain Specific Language) based on JSON
|
||||
* Good, because it is a well documented and powerful syntax
|
||||
* Good, because it is very close to the Elasticsearch and the Solr syntax which enhances compatibility
|
||||
* Good, because there is a stable and well tested go client which brings a query builder
|
||||
* Good, because it could be used as the query language which supports different search backends by just implementing what is needed for our usecase
|
||||
* Bad, because it adds complexity and fulfilling all the different query usecases can be an "uphill battle"
|
||||
* Good, because it could be used as the query language which supports different search backends by just implementing what is needed for our use-case
|
||||
* Bad, because it adds complexity and fulfilling all the different query use-cases can be an "uphill battle"
|
||||
|
||||
## Links
|
||||
|
||||
|
||||
Reference in New Issue
Block a user