Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Discussion for better URLS: NOT MERGE #3261

Closed
wants to merge 27 commits into from
Closed
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
4d6a0b1
url proposal
diocas Mar 1, 2022
dc484cb
generate config file for accounts service
wkloucek Feb 1, 2022
59b6bbc
config docs prototype
Mar 1, 2022
92c76e9
First version of the envvar docs generator
Mar 1, 2022
4751e60
remove config docs prototype
Mar 1, 2022
08fd1aa
add config descriptions
Mar 1, 2022
7b65d4a
update reva to include decomposedfs nodes-per-space (#3228)
butonic Mar 2, 2022
2a4f4b7
include env config options in the docs
Mar 2, 2022
4d3326b
include config env extractor to docs-generate step
Mar 2, 2022
9747eb2
revert ocisConfig changes
wkloucek Mar 2, 2022
8b91889
revert ocisConfig changes part 2
wkloucek Mar 2, 2022
37c993a
Add output to configenvextractor
dragonchaser Mar 2, 2022
3971f00
remove generated configvars files from repo
wkloucek Mar 2, 2022
985260f
remove config file related code
wkloucek Mar 2, 2022
4a50d39
revert ocisConfig changes part 3
wkloucek Mar 2, 2022
e5b05a4
use docs/docs-generate also in CI
wkloucek Mar 2, 2022
56e486b
Add missing weight to header to fix menu sorting
dragonchaser Mar 2, 2022
39dcae3
graph: Add some validation for username and email
rhafer Mar 2, 2022
3692e2c
graph: Assign new user the default user role
rhafer Mar 2, 2022
98e5a6c
[full-ci] Bump web v5.2.0-rc.x (#3249)
fschade Mar 2, 2022
0097a47
Bump github.com/grpc-ecosystem/grpc-gateway/v2 from 2.7.3 to 2.8.0
dependabot[bot] Mar 3, 2022
f71d28b
[full-ci] bring back web master for drone env (#3256)
fschade Mar 3, 2022
4f9f118
add changes
labkode Mar 3, 2022
5a4789d
Merge remote-tracking branch 'up/master' into url_docs_update
labkode Mar 3, 2022
0da55e3
fix typo
labkode Mar 3, 2022
3da2a68
fix typos
labkode Mar 3, 2022
4d65c0e
fix
labkode Mar 3, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions docs/ocis/adr/0011-global-url-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -318,3 +318,60 @@ Public links would have the same format: `https://<host>/files?id=<resource_id>`
{{< 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.
{{< /hint >}}


## CERN Proposal for cleaner and user friendly URLs

We believe that URLs exposed in the browser address are a critical area to be properly maintained and evolved. Changes to bookmarked URLs can and will break user behaviour.
We think that the current URLs exposed in the recent changes in Web can be improved and we propose some changes for discussion.
We have also realized that this ADR is outdated and does not reflect the current URLs used in the Web: spaces are not taken into account.

The way this section is written is to start a discussion to formulate better URLs and make a more formalised proposal to this document.

We propose you to take a look at the following examples and the inner motivations for improvement:

### Examples

| Current | Proposed |
|---------|----------|
| https://cernbox.cern.ch/files/spaces/personal/home/eos/user/d/dalvesde?items-per-page=100&sort-by=name&sort-dir=asc | https://cernbox.cern.ch/files/spaces/eos/user/d/dalvesde?items-per-page=100&sort-by=name&sort-dir=asc |
| https://cernbox.cern.ch/draw-io/files-spaces-personal-home/files/dalvesde/eos/user/d/dalvesde/cbox%20transition.drawio?contextRouteParams.storage=home&contextRouteParams.item=/eos/user/d/dalvesde | https://cernbox.cern.ch/draw-io/spaces/eos/user/d/dalvesde/cbox%20transition.drawio?previous=/files/spaces/eos/user/d/dalvesde |
| https://cernbox.cern.ch/external/files-spaces-personal-home/eoshome-d!1377773/Microsoft%20Office?contextRouteParams.storage=home&contextRouteParams.item=%2Feos%2Fuser%2Fd%2Fdalvesde | https://cernbox.cern.ch/external/spaces/eos/user/d/dalvesde/New%20file.docx?app=microsoft-office&previous=/files/spaces/eos/user/d/dalvesde |
| https://cernbox.cern.ch/files/public/show/sstLvrDFEpxwwxL?items-per-page=100 | https://cernbox.cern.ch/files/public/sstLvrDFEpxwwxL?items-per-page=100 ?? (do we need `show`?) |
| https://cernbox.cern.ch/external/files-public-files/eoshome-d!2639/Microsoft%20Office?contextRouteParams.item=sstLvrDFEpxwwxL&public-token=sstLvrDFEpxwwxL | https://cernbox.cern.ch/external/public/sstLvrDFEpxwwxL/New%20file.docx?app=microsoft-office&previous=/files/public/sstLvrDFEpxwwxL |


* We strip off `personal/home` as it does not bring any value to the URL and makes the URL relative to the current user, making it impossible to just copy and paste the URL to be reused by another user.
Copy link
Contributor

@micbar micbar Mar 4, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. The current implementation is still WIP. personal is used to determine which view to render, eg personal or projects. The plan is to rely on the GraphAPI /drives endpoint to distinguish spaces by driveType (personal, project).

home is legacy (resolves to the old webdav URL) and will be dropped when switching to aliases.

https://cloud.owncloud.com/files/spaces/personal/einstein/relative/path/to/file.txt.
Here, personal/einstein is the alias for Albert Einsteins personal space.

Example

A technical URL would look like

https://cernbox.cern.ch/files/spaces/95b4c6f6-d8f2-4976-b0a3-1b016bdfcb7e/d/dalvesde/relative/path/to/file.txt.

To make the URL human-readable we replace the UUID with an alias.
https://cernbox.cern.ch/files/spaces/eos/users/d/dalvesde/relative/path/to/file.txt

The WebUI discovers the spaces using the /drives Endpoint. For CERNBox it can return a space with the alias eos/users and the id:95b4c6f6-d8f2-4976-b0a3-1b016bdfcb7e. This aliasing allows the WebUI to use human-readable URLs and translate the alias back into a UUID which is then used to make the actual WebDAV Requests.

The problem with aliases is, that they are not unique, can be customized and might clash. Therefore the UUID is always appended as an URL Parameter ?id=95b4c6f6-d8f2-4976-b0a3-1b016bdfcb7e

Future CERNBox URL

https://cernbox.cern.ch/files/spaces/eos/users/d/dalvesde/relative/path/to/file.txt?id=95b4c6f6-d8f2-4976-b0a3-1b016bdfcb7e

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important regarding timeline: the ticket owncloud/web#6448 which is part of the current sprint (to be done by 18th of March) is a requirement for making the points above possible, because one part of the ticket is to switch over from hardcoded dav endpoints to fully relying on the GraphAPI /drives endpoint for discovering dav endpoints.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The API Endpoint https://cernbox.cern.ch/graph/v1/me/drives can be implemented for CERNBox using a static list of existing storages.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The beauty of it is the forward compatibility to a EOS driver which implements spaces.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact you will be stuck with the cernbox web fork after owncloud/web#6448 is done and you don't provide the static list of existing storages that @micbar mentioned.

* The files app works with slashes (files/spaces/personal/home/) and the application works with dashes (files-spaces-personal-home). We find no sense to this distinction.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having the origin route name in the path of app routes is only an intermediate solution. We plan to move the origin route name to a query parameter. For apps in the web monorepo this is already very easy and straightforward to use.

The origin route name is needed to go back to where the user came from when closing an app (e.g. when closing the mediaviewer, going back to a public link or the all files page respectively).

Applications should not behave differently that the files app (another application).
* We find the usage of query parameters `contextRouteParams.*` confusing and we prefer to opt for a more natural value (the previous url) with the `previous` query parameter. Note that this query parameter should only be used for applications rendered inside the Web (not for external applications opening in a tab).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy to give it a different name. I'd opt for origin, as previous implies a sequence.


### Preserving the possibility to copy and paste URLs based on paths

We would like to register `eos` as a space alias, so that we can continue providing the nominal file path: `https://<host>/files/spaces/eos/user/<letter>/<username>/<relative/path/to/resource>`.
The usage of UUIDs is not user friendly and does not bring semantic meaning for the user.


### Application URLs

Applications are a key technology enables for users and we want users to be fully engaged in a rich experience by using a vast array of applications inside the OCIS platform, not limiting the usage to just uploading and downloading files. Therefore, we believe application URLs should be a fundamental design choice alongside the files application routes, providing (and enforcing) application developers to follow guidelines for url routing.

In general, urls should be of the type:

* `<app-name>/</namespaced/alias></relative/path/to/resource>` or
* `<app-name>/public/<token></relative/path/to/resource>` for public links (allowing to distinguish if they need to be authenticated or not)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We already discussed dedicated public application routes with you in the past and opted for the solution of providing the origin route name via URL. It was a conscious design decision for oCIS to not make a difference between public and private links anymore. Actively distinguishing that in the path feels wrong to us.

Also, regarding developer experience, it seems to be an unnecessary effort for developers to define routes twice (once for authenticated, once for public context). When we have the origin route name in the query parameters it will be as simple as using a small set of composables in your self developed app to get the authentication, file retrieval and back-navigation basically for free. At the moment this is only possible for apps in the web monorepo.


Example: `https://<host>/draw-io/spaces/eos/user/d/dalvesde/CERNBox/cbox transition.drawio`

This would preserve the exact same schema used in the files app (just the app name changes). In order to know where to return on close, just add a `previous` query parameter with the previous route.

We would also recommend that the previous route is ommited from applications opened in a new tab, as closing the tab should be the recommended way of getting back to the previously opened files.

#### Special case: external app
This application acts as bridge to other (external) applications, hence the name.

Two options:

* `/external/<app-name>/full/path/to/doc` (where app-name can be "default")
* `/external/full/path/to/doc?app=<app-name>` (where ommiting the app name opens the default)