Skip to content

Commit

Permalink
feat: Add support for WebSocketSubscription2021
Browse files Browse the repository at this point in the history
  • Loading branch information
joachimvh committed Nov 9, 2022
1 parent cbc07c6 commit b1f7a6a
Show file tree
Hide file tree
Showing 54 changed files with 1,173 additions and 56 deletions.
1 change: 1 addition & 0 deletions .componentsignore
Expand Up @@ -23,6 +23,7 @@
"Readonly",
"RegExp",
"Server",
"SetMultiMap",
"Shorthand",
"SubscriptionType",
"Template",
Expand Down
27 changes: 22 additions & 5 deletions RELEASE_NOTES.md
Expand Up @@ -6,6 +6,8 @@

- The server can be configured to use [ACP](https://solidproject.org/TR/acp) instead of WebACL.
`config/file-acp.json` is an example of a configuration that uses this authorization scheme instead.
- Support for the new [WebSocket Notification protocol](https://solidproject.org/TR/websocket-subscription-2021)
was added.

### Data migration

Expand All @@ -22,6 +24,10 @@ The following changes pertain to the imports in the default configs:

- All default configurations which had setup disabled have been updated to also disable registration.
This is done to prevent configurations with accidental nested storage containers.
- All references to WebSockets have been removed from the `http/middleware` and `http/server-factory` imports.
- A new `http/notifications` set of import options have been added
to determine which notification specification a CSS instance should use.
All default configurations have been updated to use `http/notifications/websockets.json`.

The following changes are relevant for v5 custom configs that replaced certain features.

Expand All @@ -30,12 +36,22 @@ The following changes are relevant for v5 custom configs that replaced certain f
- `/app/main/default.json` now imports the above config file.
- All files configuring template engines.
- Several minor changes due to support ACP.
- `ldp/authorization/*`
- `/ldp/authorization/*`
- Resource generation was changed to there is 1 reusable resource generator.
- `init/initializers/*`
- `setup/handlers/setup.json`
- `identity/access/initializers/*`
- `identity/pod/*`
- `/init/initializers/*`
- `/setup/handlers/setup.json`
- `/identity/access/initializers/*`
- `/identity/pod/*`
- Creating an HTTP(S) server is now separate from attaching a handler to it.
- `/http/server-factory/*`
- The WebSocket middleware was moved to the relevant WebSocket configuration.
- `/http/middleware/*`
- Storage description support was added.
- `/http/handler/*`
- `/ldp/metadata-writer/*`
- Notification support was added.
- `/http/handler/*`
- `/notifications/*`

### Interface changes

Expand All @@ -50,6 +66,7 @@ These changes are relevant if you wrote custom modules for the server that depen
- `TemplatedResourcesGenerator` has been renamed to `BaseResourcesGenerator` and has a different interface now.
- `CredentialSet` was replaced by a single `Credentials` interface.
This impacts all authentication and authorization related classes.
- `HttpServerFactory.startServer` function was renamed to `createServer` and is no longer expected to start the server.

## v5.1.0

Expand Down
2 changes: 1 addition & 1 deletion config/default.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
2 changes: 1 addition & 1 deletion config/dynamic.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
1 change: 1 addition & 0 deletions config/example-https-file.json
Expand Up @@ -7,6 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/websockets.json",

"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
1 change: 1 addition & 0 deletions config/file-acp.json
Expand Up @@ -7,6 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
2 changes: 1 addition & 1 deletion config/file-no-setup.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
2 changes: 1 addition & 1 deletion config/file.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
23 changes: 15 additions & 8 deletions config/http/README.md
Expand Up @@ -14,19 +14,26 @@ Sets up all the handlers a request will potentially pass through.
A set of handlers that will always be run on all requests to add some metadata
and then pass the request along.

* *no-websockets*: The default setup but without the websocket-related metadata.
* *websockets*: The default setup with several handlers.
* *default*: The default setup with several handlers.

## Notifications

Determines how notifications should be sent out from the server when resources change.

* *disabled*: No notifications are sent out.
* *legacy-websocket*: Follows the legacy Solid WebSocket
[specification](https://github.com/solid/solid-spec/blob/master/api-websockets.md).
* *websockets*: Follows the WebSocketSubscription2021
[specification](https://solidproject.org/TR/websocket-subscription-2021).

## Server-Factory

The factory used to create the actual server object.

* *no-websockets*: Only HTTP.
* *websockets*: HTTP and websockets.
* *https-no-websockets*: Only HTTPS. Adds 2 new CLI params to set the key/cert paths.
* *https-websockets*: HTTPS and websockets. Adds 2 new CLI params to set the key/cert paths.
* *https-example*: An example configuration to use HTTPS directly at the server (instead of at a reverse proxy)
by adding the key/cert paths to the config itself.
* *http*: A HTTP server.
* *https*: A HTTPS server.
* *https-no-cli-example*: An example of how to set up an HTTPS server
by defining the key/cert paths directly in the config itself.

## Static

Expand Down
6 changes: 3 additions & 3 deletions config/http/handler/handlers/storage-description.json
Expand Up @@ -2,8 +2,8 @@
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^5.0.0/components/context.jsonld",
"@graph": [
{
"comment": "The suffix appended to a storage container to find its description resource.",
"@id": "urn:solid-server:default:variable:storageDescriptionSuffix",
"comment": "The relative path appended to a storage container URL to find its description resource.",
"@id": "urn:solid-server:default:variable:storageDescriptionPath",
"valueRaw": ".well-known/solid"
},
{
Expand All @@ -22,7 +22,7 @@
"operationHandler": {
"@type": "StorageDescriptionHandler",
"store": { "@id": "urn:solid-server:default:ResourceStore" },
"suffix": { "@id": "urn:solid-server:default:variable:storageDescriptionSuffix" },
"path": { "@id": "urn:solid-server:default:variable:storageDescriptionPath" },
"converter": { "@id": "urn:solid-server:default:RepresentationConverter" },
"describer": { "@id": "urn:solid-server:default:StorageDescriber" }
}
Expand Down
2 changes: 1 addition & 1 deletion config/http/notifications/base/description.json
Expand Up @@ -14,6 +14,6 @@
"@type": "RelativePathInteractionRoute",
"base": { "@id": "urn:solid-server:default:variable:baseUrl" },
"relativePath": "/.notifications/"
},
}
]
}
18 changes: 18 additions & 0 deletions config/http/notifications/websockets.json
@@ -0,0 +1,18 @@
{
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^5.0.0/components/context.jsonld",
"import": [
"css:config/http/notifications/base/description.json",
"css:config/http/notifications/base/handler.json",
"css:config/http/notifications/base/listener.json",
"css:config/http/notifications/base/storage.json",
"css:config/http/notifications/websockets/description.json",
"css:config/http/notifications/websockets/handler.json",
"css:config/http/notifications/websockets/http.json",
"css:config/http/notifications/websockets/subscription.json"
],
"@graph": [
{
"comment": "All the relevant components are made in the specific imports seen above."
}
]
}
18 changes: 18 additions & 0 deletions config/http/notifications/websockets/description.json
@@ -0,0 +1,18 @@
{
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^5.0.0/components/context.jsonld",
"@graph": [
{
"@id": "urn:solid-server:default:StorageDescriber",
"@type": "ArrayUnionHandler",
"handlers": [
{
"comment": "Handles the storage description triples used for discovery of a WebSocketSubscription2021 endpoint.",
"@type": "NotificationDescriber",
"route": { "@id": "urn:solid-server:default:WebSocket2021Route" },
"relative": "#websocketNotification",
"type": "http://www.w3.org/ns/solid/notifications#WebSocketSubscription2021"
}
]
}
]
}
31 changes: 31 additions & 0 deletions config/http/notifications/websockets/handler.json
@@ -0,0 +1,31 @@
{
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^5.0.0/components/context.jsonld",
"@graph": [
{
"comment": "Handles the generation and serialization of notifications for WebSocketSubscription2021.",
"@id": "urn:solid-server:default:WebSocket2021NotificationHandler",
"@type": "TypedNotificationHandler",
"type": "WebSocketSubscription2021",
"source": {
"@type": "ComposedNotificationHandler",
"generator": { "@id": "urn:solid-server:default:BaseNotificationGenerator" },
"serializer": { "@id": "urn:solid-server:default:BaseNotificationSerializer" },
"emitter": { "@id": "urn:solid-server:default:WebSocket2021Emitter" }
}
},
{
"comment": "Emits serialized notifications through WebSockets.",
"@id": "urn:solid-server:default:WebSocket2021Emitter",
"@type": "WebSocket2021Emitter",
"socketMap": { "@id": "urn:solid-server:default:WebSocketMap" }
},

{
"@id": "urn:solid-server:default:NotificationHandler",
"@type": "WaterfallHandler",
"handlers": [
{ "@id": "urn:solid-server:default:WebSocket2021NotificationHandler" }
]
}
]
}
46 changes: 46 additions & 0 deletions config/http/notifications/websockets/http.json
@@ -0,0 +1,46 @@
{
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^5.0.0/components/context.jsonld",
"@graph": [
{
"comment": "Catches newly opened WebSockets and verifies if they belong to a subscription.",
"@id": "urn:solid-server:default:WebSocket2021Listener",
"@type": "WebSocket2021Listener",
"storage": { "@id": "urn:solid-server:default:SubscriptionStorage" },
"route": { "@id": "urn:solid-server:default:WebSocket2021Route" },
"handler": {
"@type": "SequenceHandler",
"handlers": [
{ "@id": "urn:solid-server:default:WebSocket2021Storer" },
{ "@id": "urn:solid-server:default:WebSocket2021StateHandler" }
]
}
},
{
"comment": "Opened WebSockets will be stored in this Map.",
"@id": "urn:solid-server:default:WebSocketMap",
"@type": "WebSocketMap"
},
{
"comment": "Stores the opened WebSockets for reuse.",
"@id": "urn:solid-server:default:WebSocket2021Storer",
"@type": "WebSocket2021Storer",
"storage": { "@id": "urn:solid-server:default:SubscriptionStorage" },
"socketMap": { "@id": "urn:solid-server:default:WebSocketMap" }
},
{
"comment": "Handles the state feature of a WebSocketSubscription2021 subscription.",
"@id": "urn:solid-server:default:WebSocket2021StateHandler",
"@type": "BaseStateHandler",
"handler": { "@id": "urn:solid-server:default:WebSocket2021NotificationHandler" },
"storage": { "@id": "urn:solid-server:default:SubscriptionStorage" }
},

{
"@id": "urn:solid-server:default:ServerConfigurator",
"@type": "ParallelHandler",
"handlers": [
{ "@id": "urn:solid-server:default:WebSocket2021Listener" }
]
}
]
}
41 changes: 41 additions & 0 deletions config/http/notifications/websockets/subscription.json
@@ -0,0 +1,41 @@
{
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^5.0.0/components/context.jsonld",
"@graph": [
{
"comment": "Handles the subscriptions targeting a WebSocketSubscription2021.",
"@id": "urn:solid-server:default:WebSocket2021Subscriber",
"@type": "OperationRouterHandler",
"baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
"allowedMethods": [ "POST" ],
"allowedPathNames": [ "/WebSocketSubscription2021/" ],
"handler": {
"@type": "NotificationSubscriber",
"subscriptionType": { "@id": "urn:solid-server:default:WebSocketSubscription2021" },
"credentialsExtractor": { "@id": "urn:solid-server:default:CredentialsExtractor" },
"permissionReader": { "@id": "urn:solid-server:default:PermissionReader" },
"authorizer": { "@id": "urn:solid-server:default:Authorizer" }
}
},
{
"@id": "urn:solid-server:default:WebSocket2021Route",
"@type": "RelativePathInteractionRoute",
"base": { "@id": "urn:solid-server:default:NotificationRoute" },
"relativePath": "/WebSocketSubscription2021/"
},
{
"comment": "Contains all the metadata relevant for a WebSocketSubscription2021.",
"@id": "urn:solid-server:default:WebSocketSubscription2021",
"@type": "WebSocketSubscription2021",
"storage": { "@id": "urn:solid-server:default:SubscriptionStorage" },
"route": { "@id": "urn:solid-server:default:WebSocket2021Route" }
},

{
"@id": "urn:solid-server:default:NotificationTypeHandler",
"@type": "WaterfallHandler",
"handlers": [
{ "@id": "urn:solid-server:default:WebSocket2021Subscriber" }
]
}
]
}
2 changes: 1 addition & 1 deletion config/https-file-cli.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/https.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
Expand Up @@ -8,7 +8,7 @@
"targetExtractor": { "@id": "urn:solid-server:default:TargetExtractor" },
"identifierStrategy": { "@id": "urn:solid-server:default:IdentifierStrategy" },
"store": { "@id": "urn:solid-server:default:ResourceStore" },
"suffix": { "@id": "urn:solid-server:default:variable:storageDescriptionSuffix" }
"path": { "@id": "urn:solid-server:default:variable:storageDescriptionPath" }
}
]
}
2 changes: 1 addition & 1 deletion config/memory-subdomains.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
2 changes: 1 addition & 1 deletion config/path-routing.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
2 changes: 1 addition & 1 deletion config/quota-file.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/public.json",
Expand Down
2 changes: 1 addition & 1 deletion config/restrict-idp.json
Expand Up @@ -7,7 +7,7 @@
"css:config/app/variables/default.json",
"css:config/http/handler/default.json",
"css:config/http/middleware/default.json",
"css:config/http/notifications/legacy-websockets.json",
"css:config/http/notifications/websockets.json",
"css:config/http/server-factory/http.json",
"css:config/http/static/default.json",
"css:config/identity/access/restricted.json",
Expand Down

0 comments on commit b1f7a6a

Please sign in to comment.