From c64a1a241ddd975f22eb223d545c938dfc8cb63c Mon Sep 17 00:00:00 2001 From: Joachim Van Herwegen Date: Mon, 27 Nov 2023 08:58:10 +0100 Subject: [PATCH] docs: Describe server feature set * docs: Describe server feature set * docs: Fix language Co-authored-by: Ted Thibodeau Jr Co-authored-by: Ruben Verborgh * docs: Emphasize parts of feature documentation --------- Co-authored-by: Ted Thibodeau Jr Co-authored-by: Ruben Verborgh --- documentation/markdown/README.md | 1 + documentation/markdown/features.md | 92 ++++++++++++++++++++++++++++++ documentation/mkdocs.yml | 2 + 3 files changed, 95 insertions(+) create mode 100644 documentation/markdown/features.md diff --git a/documentation/markdown/README.md b/documentation/markdown/README.md index 7c35a6cc0..be410a27c 100644 --- a/documentation/markdown/README.md +++ b/documentation/markdown/README.md @@ -29,6 +29,7 @@ the [changelog](https://github.com/CommunitySolidServer/CommunitySolidServer/blo ## Using the server +* [An overview of the main features of the server](features.md) * [Quickly starting the server](usage/starting-server.md) * [Basic example HTTP requests](usage/example-requests.md) * [Editing the metadata of a resource](usage/metadata.md) diff --git a/documentation/markdown/features.md b/documentation/markdown/features.md new file mode 100644 index 000000000..2975b3325 --- /dev/null +++ b/documentation/markdown/features.md @@ -0,0 +1,92 @@ +# Features + +Below is a non-exhaustive listing of the features available to a server instance, +depending on the chosen configuration. +The core feature of the CSS is that it uses **dependency injection** to configure its components, +so any of the features below can always be adapted or replaced with custom components if required. +It can also be used to configure dummy components for debugging, development, or experimentation purposes. +See this [tutorial](https://github.com/CommunitySolidServer/tutorials/blob/main/custom-configurations.md) +and/or this [example repository](https://github.com/CommunitySolidServer/hello-world-component) +for more information on that. + +To generate configurations with some of these features enabled/disabled, +you can use the **[configuration generator](https://communitysolidserver.github.io/configuration-generator/)**. + +## Authentication + +Clients are identified based on the contents of **DPoP** tokens, +as described in the [**Solid-OIDC** specification](https://solidproject.org/TR/oidc). + +The server also provides several dummy components that can be used here, +to either always identify the client as a fixed WebID, +or to allow the WebID to be set directly in the `Authorization` header. +These can be configured by changing the `ldp/authentication` import in your configuration. + +## Authorization + +Two authorization mechanisms are implemented for determining who has access to resources: + +* **[Web Access Control](https://solidproject.org/TR/wac)** +* **[Access Control Policy](https://solidproject.org/TR/acp)** + +Alternatively, the server can be configured to not have any kind of authorization and allow full access to all resources. + +## Solid Protocol + +The **[Solid Protocol](https://solidproject.org/TR/protocol)** is supported. + +Requests to the server support **content negotiation** for common RDF formats. + +Binary **[range headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range)** are supported. + +[`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) and `Last-Modified` headers are supported. +These can be used for **[conditional requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests)**. + +`PATCH` requests targeting RDF resources can be made with **N3 Patch** or **SPARQL Update** bodies. + +The server can be configured to store data in **memory**, on the **file system**, or through a **SPARQL endpoint**. +Similarly, the locking system that is used to prevent data conflicts +can be configured to store locks in memory, on the file system, or in a Redis store, or it can be disabled. + +Multiple **worker threads** can be used when starting the server. + +## Account management + +Accounts can be created on the server with which users can perform the following actions, +through either a **JSON** or an **HTML** API: + +* Add **email/password** combinations which can be used to log in. +* Create **pods**, which are containers on the server over which the user has full control. +* Link **WebIDs** to the account. When using [Solid-OIDC](https://solidproject.org/TR/oidc), + the user can identify as any of these. + For external WebIDs, the server requires the user to add a triple as identification, + but this can be disabled if needed. +* Create **client credentials**, which can be used to authenticate without using the browser. + More information on these can be found [here](../usage/client-credentials.md). +* It is possible to use Solid-OIDC to limit access to certain parts of the account API. + More information on this can be found [here](../usage/identity-provider.md#access). + +Using these accounts, the server can generate tokens +to support **[Solid-OIDC](https://solidproject.org/TR/oidc)** authentication. + +### Pods + +The server keeps track of the **pod owners**, +which is a list of WebIDs which have full control access over all resources contained within. +Owners can be added to and removed from a pod. + +Pod URLs can be minted as either +**subdomain**, `http://pod.example.com/`, or **suffix**, `http://example.com/pod/`. + +When starting the server, a configuration file can be provided +to immediately create one or more accounts on the server with their own pods. +See the [documentation](../usage/seeding-pods.md) for more information. + +## Notifications + +CSS supports v0.2.0 of the **[Solid Notifications Protocol](https://solidproject.org/TR/notifications-protocol)**. +Specifically it supports the Notification Types +[WebSocketChannel2023](https://solid.github.io/notifications/websocket-channel-2023) +and [WebhookChannel2023](https://solid.github.io/notifications/webhook-channel-2023). + +More documentation on notifications can be found [here](../usage/notifications.md). diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 45b53fed7..797dcf788 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -77,6 +77,8 @@ extra: nav: - Welcome: - README.md + - Features: + - features.md - Usage: - Example request: usage/example-requests.md - Metadata: usage/metadata.md