mirror of
https://github.com/CommunitySolidServer/CommunitySolidServer.git
synced 2024-10-03 14:55:10 +00:00
Deployed 9a5fc67 to 5.x with MkDocs 1.3.1 and mike 1.1.2
This commit is contained in:
ci-bot
parent
7c43e55d5c
commit
12e9256884
@ -952,7 +952,7 @@ to link all class instances together,
|
||||
and uses <a href="https://github.com/LinkedSoftwareDependencies/Components-Generator.js">Components-Generator.js</a>
|
||||
to automatically generate the necessary description configurations of all classes.
|
||||
This framework allows us to configure our components in a JSON file.
|
||||
The advantage of this is that changing the configuration of components does not require any changes to the code,
|
||||
The advantage of this is that changing the configuration of components does not require any changes to the code,
|
||||
as one can just change the default configuration file, or provide a custom configuration file.</p>
|
||||
<p>More information can be found in the Components.js <a href="https://componentsjs.readthedocs.io/">documentation</a>,
|
||||
but a summarized overview can be found below.</p>
|
||||
@ -967,7 +967,7 @@ or they will not get a component file.</p>
|
||||
All the community server configurations can be found in
|
||||
the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/tree/main/config/"><code>config</code> folder</a>.
|
||||
That folder also contains information about how different pre-defined configurations can be used.</p>
|
||||
<p>A single component in such a configuration file might look as follows:
|
||||
<p>A single component in such a configuration file might look as follows:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"comment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Storage used for account management."</span><span class="p">,</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"@id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"urn:solid-server:default:AccountStorage"</span><span class="p">,</span><span class="w"></span>
|
||||
@ -976,14 +976,17 @@ That folder also contains information about how different pre-defined configurat
|
||||
<span class="w"> </span><span class="nt">"baseUrl"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"@id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"urn:solid-server:default:variable:baseUrl"</span><span class="w"> </span><span class="p">},</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"container"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/.internal/accounts/"</span><span class="w"></span>
|
||||
<span class="p">}</span><span class="w"></span>
|
||||
</code></pre></div></p>
|
||||
<p>With the corresponding constructor of the <code>JsonResourceStorage</code> class:
|
||||
</code></pre></div>
|
||||
<p>With the corresponding constructor of the <code>JsonResourceStorage</code> class:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="k">public</span><span class="w"> </span><span class="kr">constructor</span><span class="p">(</span><span class="nx">source</span><span class="o">:</span><span class="w"> </span><span class="kt">ResourceStore</span><span class="p">,</span><span class="w"> </span><span class="nx">baseUrl</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">,</span><span class="w"> </span><span class="nx">container</span><span class="o">:</span><span class="w"> </span><span class="kt">string</span><span class="p">)</span><span class="w"></span>
|
||||
</code></pre></div></p>
|
||||
<p>The important elements here are the following:
|
||||
* <code>"comment"</code>: <em>(optional)</em> A description of this component.
|
||||
* <code>"@id"</code>: <em>(optional)</em> A unique identifier of this component, which allows it to be used as parameter values in different places.
|
||||
* <code>"@type"</code>: The class name of the component. This must be a TypeScript class name that is exported via <code>index.ts</code>.</p>
|
||||
</code></pre></div>
|
||||
<p>The important elements here are the following:</p>
|
||||
<ul>
|
||||
<li><code>"comment"</code>: <em>(optional)</em> A description of this component.</li>
|
||||
<li><code>"@id"</code>: <em>(optional)</em> A unique identifier of this component, which allows it to be used as parameter values in
|
||||
different places.</li>
|
||||
<li><code>"@type"</code>: The class name of the component. This must be a TypeScript class name that is exported via <code>index.ts</code>.</li>
|
||||
</ul>
|
||||
<p>As you can see from the constructor, the other fields are direct mappings from the constructor parameters.
|
||||
<code>source</code> references another object, which we refer to using its identifier <code>urn:solid-server:default:ResourceStore</code>.
|
||||
<code>baseUrl</code> is just a string, but here we use a variable that was set before calling Components.js
|
||||
|
||||
@ -981,9 +981,9 @@ These then get converted into Components.js variables and are used to instantiat
|
||||
KeyExtractor("<br>KeyExtractor")
|
||||
AssetPathExtractor("<br>AssetPathExtractor")
|
||||
end</code></pre>
|
||||
<p>The <code>CliResolver</code> (<code>urn:solid-server-app-setup:default:CliResolver</code>) is simply a way
|
||||
to combine both the <code>CliExtractor</code> (<code>urn:solid-server-app-setup:default:CliExtractor</code>)
|
||||
and <code>ShorthandResolver</code> (<code>urn:solid-server-app-setup:default:ShorthandResolver</code>)
|
||||
<p>The <code>CliResolver</code> (<code>urn:solid-server-app-setup:default:CliResolver</code>) is simply a way
|
||||
to combine both the <code>CliExtractor</code> (<code>urn:solid-server-app-setup:default:CliExtractor</code>)
|
||||
and <code>ShorthandResolver</code> (<code>urn:solid-server-app-setup:default:ShorthandResolver</code>)
|
||||
into a single object and has no other function.</p>
|
||||
<p>Which arguments are supported and which Components.js variables are generated
|
||||
can depend on the configuration that is being used.
|
||||
|
||||
@ -1004,7 +1004,7 @@
|
||||
|
||||
|
||||
<h1 id="handling-http-requests">Handling HTTP requests<a class="headerlink" href="#handling-http-requests" title="Permanent link">¶</a></h1>
|
||||
<p>The direction of the arrows was changed slightly here to make the graph readable.
|
||||
<p>The direction of the arrows was changed slightly here to make the graph readable.</p>
|
||||
<pre class="mermaid"><code>flowchart LR
|
||||
HttpHandler("<strong>HttpHandler</strong><br>SequenceHandler")
|
||||
HttpHandler --> HttpHandlerArgs
|
||||
@ -1032,7 +1032,7 @@
|
||||
SetupHandler --> OidcHandler
|
||||
OidcHandler --> AuthResourceHttpHandler
|
||||
AuthResourceHttpHandler --> IdentityProviderHttpHandler
|
||||
IdentityProviderHttpHandler --> LdpHandler</code></pre></p>
|
||||
IdentityProviderHttpHandler --> LdpHandler</code></pre>
|
||||
<p>The <code>HttpHandler</code> is responsible for handling an incoming HTTP request.
|
||||
The request will always first go through the <code>Middleware</code>,
|
||||
where certain required headers will be added such as CORS headers.</p>
|
||||
@ -1041,11 +1041,11 @@ to find the first handler that understands the request,
|
||||
with the <code>LdpHandler</code> at the bottom being the catch-all default.</p>
|
||||
<h2 id="staticassethandler">StaticAssetHandler<a class="headerlink" href="#staticassethandler" title="Permanent link">¶</a></h2>
|
||||
<p>The <code>urn:solid-server:default:StaticAssetHandler</code> matches exact URLs to static assets which require no further logic.
|
||||
An example of this is the favicon, where the <code>/favicon.ico</code> URL
|
||||
An example of this is the favicon, where the <code>/favicon.ico</code> URL
|
||||
is directed to the favicon file at <code>/templates/images/favicon.ico</code>.
|
||||
It can also map entire folders to a specific path, such as <code>/.well-known/css/styles/</code> which contains all stylesheets.</p>
|
||||
<h2 id="setuphandler">SetupHandler<a class="headerlink" href="#setuphandler" title="Permanent link">¶</a></h2>
|
||||
<p>The <code>urn:solid-server:default:SetupHandler</code> is responsible
|
||||
<p>The <code>urn:solid-server:default:SetupHandler</code> is responsible
|
||||
for redirecting all requests to <code>/setup</code> until setup is finished,
|
||||
thereby ensuring that setup needs to be finished before anything else can be done on the server,
|
||||
and handling the actual setup request that is sent to <code>/setup</code>.
|
||||
|
||||
@ -1040,7 +1040,7 @@ while the <code>WorkerInitializer</code> will trigger for every worker thread.
|
||||
Although if your server setup is single-threaded, which is the default,
|
||||
there is no relevant difference between those two.</p>
|
||||
<h3 id="primaryinitializer">PrimaryInitializer<a class="headerlink" href="#primaryinitializer" title="Permanent link">¶</a></h3>
|
||||
<p><pre class="mermaid"><code>flowchart TD
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
PrimaryInitializer("<strong>PrimaryInitializer</strong><br>ProcessHandler")
|
||||
PrimaryInitializer --> PrimarySequenceInitializer("<strong>PrimarySequenceInitializer</strong><br>SequenceHandler")
|
||||
PrimarySequenceInitializer --> PrimarySequenceInitializerArgs
|
||||
@ -1054,9 +1054,9 @@ there is no relevant difference between those two.</p>
|
||||
|
||||
CleanupInitializer --> PrimaryParallelInitializer
|
||||
PrimaryParallelInitializer --> WorkerManager</code></pre>
|
||||
The above is a simplification of all the initializers that are present in the <code>PrimaryInitializer</code>
|
||||
<p>The above is a simplification of all the initializers that are present in the <code>PrimaryInitializer</code>
|
||||
as there are several smaller initializers that also trigger but are less relevant here.</p>
|
||||
<p>The <code>CleanupInitializer</code> is an initializer that cleans up anything
|
||||
<p>The <code>CleanupInitializer</code> is an initializer that cleans up anything
|
||||
that might have remained from a previous server start
|
||||
and could impact behaviour.
|
||||
Relevant components in other parts of the configuration are responsible for adding themselves to this array if needed.
|
||||
@ -1065,7 +1065,7 @@ An example of this is file-based locking components which might need to remove a
|
||||
This makes it easier for users to add initializers by being able to append to its handlers.</p>
|
||||
<p>The <code>WorkerManager</code> is responsible for setting up the worker threads, if any.</p>
|
||||
<h3 id="workerinitializer">WorkerInitializer<a class="headerlink" href="#workerinitializer" title="Permanent link">¶</a></h3>
|
||||
<p><pre class="mermaid"><code>flowchart TD
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
WorkerInitializer("<strong>WorkerInitializer</strong><br>ProcessHandler")
|
||||
WorkerInitializer --> WorkerSequenceInitializer("<strong>WorkerSequenceInitializer</strong><br>SequenceHandler")
|
||||
WorkerSequenceInitializer --> WorkerSequenceInitializerArgs
|
||||
@ -1077,13 +1077,13 @@ This makes it easier for users to add initializers by being able to append to it
|
||||
end
|
||||
|
||||
WorkerParallelInitializer --> ServerInitializer</code></pre>
|
||||
The <code>WorkerInitializer</code> is quite similar to the <code>PrimaryInitializer</code> but triggers once per worker thread.
|
||||
<p>The <code>WorkerInitializer</code> is quite similar to the <code>PrimaryInitializer</code> but triggers once per worker thread.
|
||||
Like the <code>PrimaryParallelInitializer</code>, the <code>WorkerParallelInitializer</code> can be used
|
||||
to add any custom initializers that need to run.</p>
|
||||
<h3 id="serverinitializer">ServerInitializer<a class="headerlink" href="#serverinitializer" title="Permanent link">¶</a></h3>
|
||||
<p>The <code>ServerInitializer</code> is the initializer that finally starts up the server by listening to the relevant port,
|
||||
once all the initialization described above is finished.
|
||||
This is an example of a component that differs based on some of the choices made during configuration.
|
||||
This is an example of a component that differs based on some of the choices made during configuration.</p>
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
ServerInitializer("<strong>ServerInitializer</strong><br>ServerInitializer")
|
||||
ServerInitializer --> WebSocketServerFactory("<strong>ServerFactory</strong><br>WebSocketServerFactory")
|
||||
@ -1092,7 +1092,7 @@ This is an example of a component that differs based on some of the choices made
|
||||
|
||||
ServerInitializer2("<strong>ServerInitializer</strong><br>ServerInitializer")
|
||||
ServerInitializer2 ---> BaseHttpServerFactory2("<strong>ServerFactory</strong><br>BaseHttpServerFactory")
|
||||
BaseHttpServerFactory2 --> HttpHandler2("<strong>HttpHandler</strong><br><i>HttpHandler</i>")</code></pre></p>
|
||||
BaseHttpServerFactory2 --> HttpHandler2("<strong>HttpHandler</strong><br><i>HttpHandler</i>")</code></pre>
|
||||
<p>Depending on if the configurations necessary for websockets are imported or not,
|
||||
the <code>urn:solid-server:default:ServerFactory</code> identifier will point to a different resource.
|
||||
There will always be a <code>BaseHttpServerFactory</code> that starts the HTTP(S) server,
|
||||
|
||||
@ -1018,8 +1018,8 @@ making a requesting agent have multiple credentials.</p>
|
||||
direction LR
|
||||
DPoPWebIdExtractor("<br>DPoPWebIdExtractor") --> BearerWebIdExtractor("<br>BearerWebIdExtractor")
|
||||
end</code></pre>
|
||||
<p>Both of the WebID extractors make use of
|
||||
the (<code>access-token-verifier</code>)[https://github.com/CommunitySolidServer/access-token-verifier] library
|
||||
<p>Both of the WebID extractors make use of
|
||||
the <a href="https://github.com/CommunitySolidServer/access-token-verifier"><code>access-token-verifier</code></a> library
|
||||
to parse incoming tokens based on the <a href="https://solid.github.io/solid-oidc/">Solid-OIDC specification</a>.
|
||||
Besides those there are always the public credentials, which everyone has.
|
||||
All these credentials then get combined into a single union object.</p>
|
||||
@ -1042,14 +1042,15 @@ based on the request contents.</p>
|
||||
PatchModesExtractor("<strong>PatchModesExtractor</strong><br><i>ModesExtractor</i>") --> MethodModesExtractor("<br>MethodModesExtractor")
|
||||
end</code></pre>
|
||||
<p>The <code>IntermediateCreateExtractor</code> is responsible if requests try to create intermediate containers with a single request.
|
||||
E.g., a PUT request to <code>/foo/bar/baz</code> should create both the <code>/foo/</code> and <code>/foo/bar/</code> containers in case they do not exist yet.
|
||||
E.g., a PUT request to <code>/foo/bar/baz</code> should create both the <code>/foo/</code> and <code>/foo/bar/</code> containers in case they do not
|
||||
exist yet.
|
||||
This extractor makes sure that <code>create</code> permissions are also checked on those containers.</p>
|
||||
<p>Modes can usually be determined based on just the HTTP methods,
|
||||
which is what the <code>MethodModesExtractor</code> does.
|
||||
A GET request will always need the <code>read</code> mode for example.</p>
|
||||
<p>The only exception are PATCH requests,
|
||||
where the necessary modes depend on the body and the PATCH type.</p>
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
PatchModesExtractor("<strong>PatchModesExtractor</strong><br>WaterfallHandler") --> PatchModesExtractorArgs
|
||||
subgraph PatchModesExtractorArgs[" "]
|
||||
N3PatchModesExtractor("<br>N3PatchModesExtractor")
|
||||
@ -1065,7 +1066,7 @@ Each reader returns all the information it can find based on the resources and m
|
||||
In the default configuration the following readers are combined when WebACL is enabled as authorization method.
|
||||
In case authorization is disabled by changing the authorization import to <code>config/ldp/authorization/allow-all.json</code>,
|
||||
this diagram is just a class that always returns all permissions.</p>
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
PermissionReader("<strong>PermissionReader</strong><br>AuxiliaryReader")
|
||||
PermissionReader --> UnionPermissionReader("<br>UnionPermissionReader")
|
||||
UnionPermissionReader --> UnionPermissionReaderArgs
|
||||
@ -1085,7 +1086,7 @@ An example of this is if the requests targets the metadata of a resource.</p>
|
||||
If one reader rejects a specific mode and another allows it, the rejection takes priority.</p>
|
||||
<p>The <code>PathBasedReader</code> rejects all permissions for certain paths.
|
||||
This is used to prevent access to the internal data of the server.</p>
|
||||
<p>The <code>OwnerPermissionReader</code> makes sure owners always have control access
|
||||
<p>The <code>OwnerPermissionReader</code> makes sure owners always have control access
|
||||
to the <a href="../../../../usage/identity-provider/#pod">pods they created on the server</a>.
|
||||
Users will always be able to modify the ACL resources in their pod,
|
||||
even if they accidentally removed their own access.</p>
|
||||
@ -1096,7 +1097,7 @@ while deleting a resource requires <code>write</code> permissions there.</p>
|
||||
<p>In case the target is an ACL resource, <code>control</code> permissions need to be checked,
|
||||
no matter what mode was generated by the <code>ModesExtractor</code>.
|
||||
The <code>WebAclAuxiliaryReader</code> makes sure this conversion happens.</p>
|
||||
<p>Finally, the <code>WebAclReader</code> implements
|
||||
<p>Finally, the <code>WebAclReader</code> implements
|
||||
the <a href="https://solidproject.org/TR/2021/wac-20210711#effective-acl-resource">efffective ACL resource algorithm</a>
|
||||
and returns the permissions it finds in that resource.
|
||||
In case no ACL resource is found this indicates a configuration error and no permissions will be granted.</p>
|
||||
|
||||
@ -1047,12 +1047,14 @@ It follows these 3 steps:</p>
|
||||
<ol>
|
||||
<li>Use the <code>RequestParser</code> to convert the incoming data into an <code>Operation</code>.</li>
|
||||
<li>Send the <code>Operation</code> to the <code>AuthorizingHttpHandler</code> to receive either a <code>Representation</code> if the operation was a success,
|
||||
or an <code>Error</code> in case something went wrong.</li>
|
||||
or an <code>Error</code> in case something went wrong.<ul>
|
||||
<li>In case of an error the <code>ErrorHandler</code> will convert the <code>Error</code> into a <code>ResponseDescription</code>.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Use the <code>ResponseWriter</code> to output the <code>ResponseDescription</code> as an HTTP response.</li>
|
||||
</ol>
|
||||
<h2 id="parsing-the-request">Parsing the request<a class="headerlink" href="#parsing-the-request" title="Permanent link">¶</a></h2>
|
||||
<p><pre class="mermaid"><code>flowchart TD
|
||||
<pre class="mermaid"><code>flowchart TD
|
||||
RequestParser("<strong>RequestParser</strong><br>BasicRequestParser") --> RequestParserArgs
|
||||
subgraph RequestParserArgs[" "]
|
||||
TargetExtractor("<strong>TargetExtractor</strong><br>OriginalUrlExtractor")
|
||||
@ -1063,7 +1065,7 @@ It follows these 3 steps:</p>
|
||||
end
|
||||
|
||||
OriginalUrlExtractor --> IdentifierStrategy("<strong>IdentifierStrategy</strong><br><i>IdentifierStrategy</i>")</code></pre>
|
||||
The <code>BasicRequestParser</code> is mostly an aggregator of multiple smaller parsers that each handle a very specific part.</p>
|
||||
<p>The <code>BasicRequestParser</code> is mostly an aggregator of multiple smaller parsers that each handle a very specific part.</p>
|
||||
<h3 id="url">URL<a class="headerlink" href="#url" title="Permanent link">¶</a></h3>
|
||||
<p>This is a single class, the <code>OriginalUrlExtractor</code>, but fulfills the very important role
|
||||
of making sure input URLs are handled consistently.</p>
|
||||
@ -1078,7 +1080,7 @@ This can differ depending on if the server uses subdomains or not.</p>
|
||||
<p>The <code>AcceptPreferenceParser</code> parses the <code>Accept</code> header and all the relevant <code>Accept-*</code> headers.
|
||||
These will all be put into the <code>preferences</code> field of an <code>Operation</code> object.
|
||||
These will later be used to handle the content negotiation.</p>
|
||||
<p>For example, when sending an <code>Accept: text/turtle; q=0.9</code> header,
|
||||
<p>For example, when sending an <code>Accept: text/turtle; q=0.9</code> header,
|
||||
this wil result in the preferences object <code>{ type: { 'text/turtle': 0.9 } }</code>.</p>
|
||||
<h3 id="headers">Headers<a class="headerlink" href="#headers" title="Permanent link">¶</a></h3>
|
||||
<p>Several other headers can have relevant metadata,
|
||||
@ -1106,7 +1108,7 @@ These will later be used to make sure the request should be aborted or not.</p>
|
||||
and if not it will throw an error.</p>
|
||||
<p>In case an error gets thrown, this will be caught by the <code>ErrorHandler</code> and converted into a <code>ResponseDescription</code>.
|
||||
The request preferences will be used to make sure the serialization is one that is preferred.</p>
|
||||
<p>Either way we will have a <code>ResponseDescription</code>,
|
||||
<p>Either way we will have a <code>ResponseDescription</code>,
|
||||
which will be sent to the <code>BasicResponseWriter</code> to convert into output headers, data and a status code.</p>
|
||||
<p>To convert the metadata into headers, it uses a <code>MetadataWriter</code>,
|
||||
which functions as the reverse of the <code>MetadataParser</code> mentioned above:
|
||||
|
||||
@ -1031,15 +1031,18 @@ The default configurations come with the following stores:</p>
|
||||
and all the entries in <code>config/storage/backend</code>.</p>
|
||||
<h2 id="monitoringstore">MonitoringStore<a class="headerlink" href="#monitoringstore" title="Permanent link">¶</a></h2>
|
||||
<p>This store emits the events that are necessary to emit notifications when resources change.</p>
|
||||
<p>There are 4 different events that can be emitted:
|
||||
- <code>this.emit('changed', identifier, activity)</code>: is emitted for every resource that was changed/effected by a call to the store.
|
||||
With activity being undefined or one of the available ActivityStream terms.
|
||||
- <code>this.emit(AS.Create, identifier)</code>: is emitted for every resource that was created by the call to the store.
|
||||
- <code>this.emit(AS.Update, identifier)</code>: is emitted for every resource that was updated by the call to the store.
|
||||
- <code>this.emit(AS.Delete, identifier)</code>: is emitted for every resource that was deleted by the call to the store.</p>
|
||||
<p>There are 4 different events that can be emitted:</p>
|
||||
<ul>
|
||||
<li><code>this.emit('changed', identifier, activity)</code>: is emitted for every resource that was changed/effected by a
|
||||
call to the store.
|
||||
With activity being undefined or one of the available ActivityStream terms.</li>
|
||||
<li><code>this.emit(AS.Create, identifier)</code>: is emitted for every resource that was created by the call to the store.</li>
|
||||
<li><code>this.emit(AS.Update, identifier)</code>: is emitted for every resource that was updated by the call to the store.</li>
|
||||
<li><code>this.emit(AS.Delete, identifier)</code>: is emitted for every resource that was deleted by the call to the store.</li>
|
||||
</ul>
|
||||
<p>A <code>changed</code> event will always be emitted if a resource was changed.
|
||||
If the correct metadata was set by the source <code>ResourceStore</code>, an additional field will be sent along indicating the type of change,
|
||||
and an additional corresponding event will be emitted, depending on what the change is.</p>
|
||||
If the correct metadata was set by the source <code>ResourceStore</code>, an additional field will be sent along indicating the
|
||||
type of change, and an additional corresponding event will be emitted, depending on what the change is.</p>
|
||||
<h2 id="indexrepresentationstore">IndexRepresentationStore<a class="headerlink" href="#indexrepresentationstore" title="Permanent link">¶</a></h2>
|
||||
<p>When doing a GET request on a container <code>/container/</code>,
|
||||
this container returns the contents of <code>/container/index.html</code> instead if HTML is the preferred response type.
|
||||
@ -1070,15 +1073,13 @@ the SPARQL backend only accepts triples for example,
|
||||
that is also handled here</p>
|
||||
<h2 id="dataaccessorbasedstore">DataAccessorBasedStore<a class="headerlink" href="#dataaccessorbasedstore" title="Permanent link">¶</a></h2>
|
||||
<p>Large parts of the requirements of the Solid protocol specification are resolved by the <code>DataAccessorBasedStore</code>:
|
||||
POST only working on containers,
|
||||
DELETE not working on non-empty containers,
|
||||
POST only working on containers, DELETE not working on non-empty containers,
|
||||
generating <code>ldp:contains</code> triples for containers, etc.
|
||||
Most of this behaviour is independent of how the data is stored which is why it can be generalized here.
|
||||
The store's name comes from the fact that it makes use of <code>DataAccessor</code>s to handle the read/write of resources.
|
||||
A <code>DataAccessor</code> is a simple interface that only focuses on handling the data.
|
||||
It does not concern itself with any of the necessary Solid checks as it assumes those have already been made.
|
||||
This means that if a storage method needs to be supported,
|
||||
only a new <code>DataAccessor</code> needs to be made,
|
||||
This means that if a storage method needs to be supported, only a new <code>DataAccessor</code> needs to be made,
|
||||
after which it can be plugged into the rest of the server.</p>
|
||||
|
||||
|
||||
|
||||
@ -572,6 +572,13 @@
|
||||
Architecture diagrams
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#features" class="md-nav__link">
|
||||
Features
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@ -915,6 +922,13 @@
|
||||
Architecture diagrams
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#features" class="md-nav__link">
|
||||
Features
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@ -932,7 +946,7 @@
|
||||
|
||||
|
||||
<h1 id="architecture-overview">Architecture overview<a class="headerlink" href="#architecture-overview" title="Permanent link">¶</a></h1>
|
||||
<p>The initial architecture document the project was started from can be found
|
||||
<p>The initial architecture document the project was started from can be found
|
||||
<a href="https://rubenverborgh.github.io/solid-server-architecture/solid-architecture-v1-3-0.pdf">here</a>.
|
||||
Many things have been added since the original inception of the project,
|
||||
but the core ideas within that document are still valid.</p>
|
||||
@ -961,17 +975,19 @@ We will use an example below to explain the formatting used throughout the archi
|
||||
end</code></pre>
|
||||
<p>Below is a summary of how to interpret such diagrams:</p>
|
||||
<ul>
|
||||
<li>Rounded red box: component instantiated in the Components.js <a href="../dependency-injection/">configuration</a>.</li>
|
||||
<li>First line: <ul>
|
||||
<li>Rounded red box: component instantiated in the Components.js <a href="../dependency-injection/">configuration</a>.<ul>
|
||||
<li>First line:<ul>
|
||||
<li><strong>Bold text</strong>: shorthand of the instance identifier. In case the full URI is not specified,
|
||||
it can usually be found by prepending <code>urn:solid-server:default:</code> to the shorthand identifier.</li>
|
||||
it can usually be found by prepending <code>urn:solid-server:default:</code> to the shorthand identifier.</li>
|
||||
<li>(empty): this instance has no identifier and is defined in the same place as its parent.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Second line: <ul>
|
||||
<li>Second line:<ul>
|
||||
<li>Regular text: The class of this instance.</li>
|
||||
<li><em>Italic text</em>: The interface of this instance.
|
||||
Will be used if the actual class is not relevant for the explanation or can differ.</li>
|
||||
<li><em>Italic text</em>: The interface of this instance.
|
||||
Will be used if the actual class is not relevant for the explanation or can differ.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Square grey box: the parameters of the linked instance.</li>
|
||||
@ -980,7 +996,7 @@ We will use an example below to explain the formatting used throughout the archi
|
||||
<p>For example, in the above, <strong>LdpHandler</strong> is a shorthand for the actual identifier <code>urn:solid-server:default:LdpHandler</code>
|
||||
and is an instance of <code>ParsingHttpHandler</code>. It has 4 parameters,
|
||||
one of which has no identifier but is an instance of <code>AuthorizingHttpHandler</code>.</p>
|
||||
<h1 id="features">Features<a class="headerlink" href="#features" title="Permanent link">¶</a></h1>
|
||||
<h2 id="features">Features<a class="headerlink" href="#features" title="Permanent link">¶</a></h2>
|
||||
<p>Below are the sections that go deeper into the features of the server and how those work.</p>
|
||||
<ul>
|
||||
<li><a href="../features/cli/">How Command Line Arguments are parsed and used</a></li>
|
||||
|
||||
@ -888,26 +888,26 @@
|
||||
<h1 id="pull-requests">Pull requests<a class="headerlink" href="#pull-requests" title="Permanent link">¶</a></h1>
|
||||
<p>The community server is fully written in <a href="https://www.typescriptlang.org/docs/home.html">Typescript</a>.</p>
|
||||
<p>All changes should be done through
|
||||
<a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork">pull requests</a>. </p>
|
||||
<a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork">pull requests</a>.</p>
|
||||
<p>We recommend first discussing a possible solution in the relevant issue
|
||||
to reduce the amount of changes that will be requested.</p>
|
||||
<p>In case any of your changes are breaking, make sure you target the next major branch (<code>versions/x.0.0</code>)
|
||||
instead of the main branch. Breaking changes include: changing interface/class signatures,
|
||||
potentially breaking external custom configurations,
|
||||
potentially breaking external custom configurations,
|
||||
and breaking how internal data is stored.
|
||||
In case of doubt you probably want to target the next major branch.</p>
|
||||
<p>We make use of <a href="https://www.conventionalcommits.org">Conventional Commits</a>.</p>
|
||||
<p>Don't forget to update the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/RELEASE_NOTES.md">release notes</a>
|
||||
<p>Don't forget to update the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/RELEASE_NOTES.md">release notes</a>
|
||||
when adding new major features.
|
||||
Also update any relevant documentation in case this is needed.</p>
|
||||
<p>When making changes to a pull request,
|
||||
<p>When making changes to a pull request,
|
||||
we prefer to update the existing commits with a rebase instead of appending new commits,
|
||||
this way the PR can be rebased directly onto the target branch
|
||||
instead of needing to be squashed.</p>
|
||||
<p>There are strict requirements from the linter and the test coverage before a PR is valid.
|
||||
These are configured to run automatically when trying to commit to git.
|
||||
Although there are no tests for it (yet), we strongly advice documenting with <a href="https://github.com/microsoft/tsdoc">TSdoc</a>.</p>
|
||||
<p>If a list of entries is alphabetically sorted,
|
||||
<p>If a list of entries is alphabetically sorted,
|
||||
such as <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/src/index.ts">index.ts</a>,
|
||||
make sure it stays that way.</p>
|
||||
|
||||
|
||||
@ -899,14 +899,18 @@
|
||||
</li>
|
||||
<li>Verify that the <code>RELEASE_NOTES.md</code> are correct.</li>
|
||||
<li><code>npm run release -- -r major</code><ul>
|
||||
<li>Automatically updates Components.js references to the new version. Committed with <code>chore(release): Update configs to vx.0.0</code>.</li>
|
||||
<li>Updates the <code>package.json</code>, and generates the new entries in <code>CHANGELOG.md</code>. Commited with <code>chore(release): Release version vx.0.0 of the npm package</code></li>
|
||||
<li>Optionally run <code>npx commit-and-tag-version -r major --dry-run</code> to preview the commands that will be run and the changes to <code>CHANGELOG.md</code>.</li>
|
||||
<li>Automatically updates Components.js references to the new version.
|
||||
Committed with <code>chore(release): Update configs to vx.0.0</code>.</li>
|
||||
<li>Updates the <code>package.json</code>, and generates the new entries in <code>CHANGELOG.md</code>.
|
||||
Commited with <code>chore(release): Release version vx.0.0 of the npm package</code></li>
|
||||
<li>Optionally run <code>npx commit-and-tag-version -r major --dry-run</code> to preview the commands that will be run
|
||||
and the changes to <code>CHANGELOG.md</code>.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>The <code>postrelease</code> script will now prompt you to manually edit the <code>CHANGELOG.md</code>.<ul>
|
||||
<li>All entries are added in separate sections of the new release according to their commit prefixes.</li>
|
||||
<li>Re-organize the entries accordingly, referencing previous releases. Most of the entries in Chores and Documentation can be removed.</li>
|
||||
<li>Re-organize the entries accordingly, referencing previous releases. Most of the entries in Chores and
|
||||
Documentation can be removed.</li>
|
||||
<li>Press any key in your terminal when your changes are ready.</li>
|
||||
<li>The <code>postrelease</code> script will amend the release commit, create an annotated tag and push changes to origin.</li>
|
||||
</ul>
|
||||
|
||||
@ -925,7 +925,7 @@ This is a good way to get started with the server and its setup.</p>
|
||||
<p>If you want to know what is new in the latest version,
|
||||
you can check out the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/RELEASE_NOTES.md">release notes</a>
|
||||
for a high level overview and information on how to migrate your configuration to the next version.
|
||||
A list that includes all minor changes can be found in
|
||||
A list that includes all minor changes can be found in
|
||||
the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/CHANGELOG.md">changelog</a></p>
|
||||
<h2 id="using-the-server">Using the server<a class="headerlink" href="#using-the-server" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
@ -944,7 +944,7 @@ the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/blob/m
|
||||
<ul>
|
||||
<li><a href="contributing/making-changes/">How to make changes to the repository</a></li>
|
||||
</ul>
|
||||
<p>For core developers with push access only: </p>
|
||||
<p>For core developers with push access only:</p>
|
||||
<ul>
|
||||
<li><a href="contributing/release/">How to release a new version</a></li>
|
||||
</ul>
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -2,92 +2,92 @@
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/core/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/dependency-injection/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/overview/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/cli/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/http-handler/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/initialization/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/protocol/authorization/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/protocol/overview/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/protocol/parsing/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/architecture/features/protocol/resource-store/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/contributing/making-changes/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/contributing/release/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/usage/client-credentials/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/usage/example-requests/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/usage/identity-provider/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/usage/metadata/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://communitysolidserver.github.io/CommunitySolidServer/5.x/usage/seeding-pods/</loc>
|
||||
<lastmod>2022-08-22</lastmod>
|
||||
<lastmod>2022-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
</urlset>
|
||||
Binary file not shown.
@ -983,7 +983,7 @@ to send along the email and password of that account to identify yourself.
|
||||
This is a temporary solution until the server has more advanced account management,
|
||||
after which this API will change.</p>
|
||||
<p>Below is example code of how to make use of these tokens.
|
||||
It makes use of several utility functions from the
|
||||
It makes use of several utility functions from the
|
||||
<a href="https://github.com/inrupt/solid-client-authn-js">Solid Authentication Client</a>.
|
||||
Note that the code below uses top-level <code>await</code>, which not all JavaScript engines support,
|
||||
so this should all be contained in an <code>async</code> function.</p>
|
||||
@ -1036,7 +1036,7 @@ This Access Token is only valid for a certain amount of time, after which a new
|
||||
<span class="p">});</span><span class="w"></span>
|
||||
|
||||
<span class="c1">// This is the Access token that will be used to do an authenticated request to the server.</span><span class="w"></span>
|
||||
<span class="c1">// The JSON also contains an "expires_in" field in seconds, </span><span class="w"></span>
|
||||
<span class="c1">// The JSON also contains an "expires_in" field in seconds,</span><span class="w"></span>
|
||||
<span class="c1">// which you can use to know when you need request a new Access token.</span><span class="w"></span>
|
||||
<span class="kd">const</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">access_token</span><span class="o">:</span><span class="w"> </span><span class="kt">accessToken</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">await</span><span class="w"> </span><span class="nx">response</span><span class="p">.</span><span class="nx">json</span><span class="p">();</span><span class="w"></span>
|
||||
</code></pre></div>
|
||||
|
||||
@ -426,6 +426,8 @@
|
||||
<input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<label class="md-nav__link md-nav__link--active" for="__toc">
|
||||
Example request
|
||||
@ -442,6 +444,8 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<label class="md-nav__title" for="__toc">
|
||||
<span class="md-nav__icon md-icon"></span>
|
||||
@ -450,65 +454,52 @@
|
||||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#interacting-with-the-server" class="md-nav__link">
|
||||
Interacting with the server
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Interacting with the server">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#put-creating-resources-for-a-given-url" class="md-nav__link">
|
||||
PUT: Creating resources for a given URL
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#post-creating-resources-at-a-generated-url" class="md-nav__link">
|
||||
POST: Creating resources at a generated URL
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#get-retrieving-resources" class="md-nav__link">
|
||||
GET: Retrieving resources
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#delete-deleting-resources" class="md-nav__link">
|
||||
DELETE: Deleting resources
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#patch-modifying-resources" class="md-nav__link">
|
||||
PATCH: Modifying resources
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#head-retrieve-resources-headers" class="md-nav__link">
|
||||
HEAD: Retrieve resources headers
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#options-retrieve-resources-communication-options" class="md-nav__link">
|
||||
OPTIONS: Retrieve resources communication options
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@ -952,6 +943,8 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<label class="md-nav__title" for="__toc">
|
||||
<span class="md-nav__icon md-icon"></span>
|
||||
@ -960,65 +953,52 @@
|
||||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#interacting-with-the-server" class="md-nav__link">
|
||||
Interacting with the server
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Interacting with the server">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#put-creating-resources-for-a-given-url" class="md-nav__link">
|
||||
PUT: Creating resources for a given URL
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#post-creating-resources-at-a-generated-url" class="md-nav__link">
|
||||
POST: Creating resources at a generated URL
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#get-retrieving-resources" class="md-nav__link">
|
||||
GET: Retrieving resources
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#delete-deleting-resources" class="md-nav__link">
|
||||
DELETE: Deleting resources
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#patch-modifying-resources" class="md-nav__link">
|
||||
PATCH: Modifying resources
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#head-retrieve-resources-headers" class="md-nav__link">
|
||||
HEAD: Retrieve resources headers
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#options-retrieve-resources-communication-options" class="md-nav__link">
|
||||
OPTIONS: Retrieve resources communication options
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@ -1035,49 +1015,47 @@
|
||||
|
||||
|
||||
|
||||
<h1>Example request</h1>
|
||||
|
||||
<h2 id="interacting-with-the-server">Interacting with the server<a class="headerlink" href="#interacting-with-the-server" title="Permanent link">¶</a></h2>
|
||||
<h3 id="put-creating-resources-for-a-given-url"><code>PUT</code>: Creating resources for a given URL<a class="headerlink" href="#put-creating-resources-for-a-given-url" title="Permanent link">¶</a></h3>
|
||||
<p>Create a plain text file:
|
||||
<h1 id="interacting-with-the-server">Interacting with the server<a class="headerlink" href="#interacting-with-the-server" title="Permanent link">¶</a></h1>
|
||||
<h2 id="put-creating-resources-for-a-given-url"><code>PUT</code>: Creating resources for a given URL<a class="headerlink" href="#put-creating-resources-for-a-given-url" title="Permanent link">¶</a></h2>
|
||||
<p>Create a plain text file:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X PUT -H <span class="s2">"Content-Type: text/plain"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"abc"</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.txt
|
||||
</code></pre></div></p>
|
||||
<p>Create a turtle file:
|
||||
</code></pre></div>
|
||||
<p>Create a turtle file:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X PUT -H <span class="s2">"Content-Type: text/turtle"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"<ex:s> <ex:p> <ex:o>."</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.ttl
|
||||
</code></pre></div></p>
|
||||
<h3 id="post-creating-resources-at-a-generated-url"><code>POST</code>: Creating resources at a generated URL<a class="headerlink" href="#post-creating-resources-at-a-generated-url" title="Permanent link">¶</a></h3>
|
||||
<p>Create a plain text file:
|
||||
</code></pre></div>
|
||||
<h2 id="post-creating-resources-at-a-generated-url"><code>POST</code>: Creating resources at a generated URL<a class="headerlink" href="#post-creating-resources-at-a-generated-url" title="Permanent link">¶</a></h2>
|
||||
<p>Create a plain text file:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X POST -H <span class="s2">"Content-Type: text/plain"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"abc"</span> <span class="se">\</span>
|
||||
http://localhost:3000/
|
||||
</code></pre></div></p>
|
||||
<p>Create a turtle file:
|
||||
</code></pre></div>
|
||||
<p>Create a turtle file:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X POST -H <span class="s2">"Content-Type: text/turtle"</span> <span class="se">\</span>
|
||||
-d <span class="s2">"<ex:s> <ex:p> <ex:o>."</span> <span class="se">\</span>
|
||||
http://localhost:3000/
|
||||
</code></pre></div></p>
|
||||
</code></pre></div>
|
||||
<p>The response's <code>Location</code> header will contain the URL of the created resource.</p>
|
||||
<h3 id="get-retrieving-resources"><code>GET</code>: Retrieving resources<a class="headerlink" href="#get-retrieving-resources" title="Permanent link">¶</a></h3>
|
||||
<p>Retrieve a plain text file:
|
||||
<h2 id="get-retrieving-resources"><code>GET</code>: Retrieving resources<a class="headerlink" href="#get-retrieving-resources" title="Permanent link">¶</a></h2>
|
||||
<p>Retrieve a plain text file:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -H <span class="s2">"Accept: text/plain"</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.txt
|
||||
</code></pre></div></p>
|
||||
<p>Retrieve a turtle file:
|
||||
</code></pre></div>
|
||||
<p>Retrieve a turtle file:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -H <span class="s2">"Accept: text/turtle"</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.ttl
|
||||
</code></pre></div></p>
|
||||
<p>Retrieve a turtle file in a different serialization:
|
||||
</code></pre></div>
|
||||
<p>Retrieve a turtle file in a different serialization:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -H <span class="s2">"Accept: application/ld+json"</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.ttl
|
||||
</code></pre></div></p>
|
||||
<h3 id="delete-deleting-resources"><code>DELETE</code>: Deleting resources<a class="headerlink" href="#delete-deleting-resources" title="Permanent link">¶</a></h3>
|
||||
</code></pre></div>
|
||||
<h2 id="delete-deleting-resources"><code>DELETE</code>: Deleting resources<a class="headerlink" href="#delete-deleting-resources" title="Permanent link">¶</a></h2>
|
||||
<div class="highlight"><pre><span></span><code>curl -X DELETE http://localhost:3000/myfile.txt
|
||||
</code></pre></div>
|
||||
<h3 id="patch-modifying-resources"><code>PATCH</code>: Modifying resources<a class="headerlink" href="#patch-modifying-resources" title="Permanent link">¶</a></h3>
|
||||
<h2 id="patch-modifying-resources"><code>PATCH</code>: Modifying resources<a class="headerlink" href="#patch-modifying-resources" title="Permanent link">¶</a></h2>
|
||||
<p>Modify a resource using <a href="https://solidproject.org/TR/protocol#n3-patch">N3 Patch</a>:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X PATCH -H <span class="s2">"Content-Type: text/n3"</span> <span class="se">\</span>
|
||||
--data-raw <span class="s2">"@prefix solid: <http://www.w3.org/ns/solid/terms#>. _:rename a solid:InsertDeletePatch; solid:inserts { <ex:s2> <ex:p2> <ex:o2>. }."</span> <span class="se">\</span>
|
||||
@ -1088,11 +1066,11 @@
|
||||
-d <span class="s2">"INSERT DATA { <ex:s2> <ex:p2> <ex:o2> }"</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.ttl
|
||||
</code></pre></div>
|
||||
<h3 id="head-retrieve-resources-headers"><code>HEAD</code>: Retrieve resources headers<a class="headerlink" href="#head-retrieve-resources-headers" title="Permanent link">¶</a></h3>
|
||||
<h2 id="head-retrieve-resources-headers"><code>HEAD</code>: Retrieve resources headers<a class="headerlink" href="#head-retrieve-resources-headers" title="Permanent link">¶</a></h2>
|
||||
<div class="highlight"><pre><span></span><code>curl -I -H <span class="s2">"Accept: text/plain"</span> <span class="se">\</span>
|
||||
http://localhost:3000/myfile.txt
|
||||
</code></pre></div>
|
||||
<h3 id="options-retrieve-resources-communication-options"><code>OPTIONS</code>: Retrieve resources communication options<a class="headerlink" href="#options-retrieve-resources-communication-options" title="Permanent link">¶</a></h3>
|
||||
<h2 id="options-retrieve-resources-communication-options"><code>OPTIONS</code>: Retrieve resources communication options<a class="headerlink" href="#options-retrieve-resources-communication-options" title="Permanent link">¶</a></h2>
|
||||
<div class="highlight"><pre><span></span><code>curl -X OPTIONS -i http://localhost:3000/myfile.txt
|
||||
</code></pre></div>
|
||||
|
||||
|
||||
@ -1127,7 +1127,7 @@
|
||||
<p>Besides implementing the <a href="https://solidproject.org/TR/protocol">Solid protocol</a>,
|
||||
the community server can also be an Identity Provider (IDP), officially known as an OpenID Provider (OP),
|
||||
following the <a href="https://solid.github.io/solid-oidc/">Solid OIDC spec</a> as much as possible.</p>
|
||||
<p>It is recommended to use the latest version
|
||||
<p>It is recommended to use the latest version
|
||||
of the <a href="https://github.com/inrupt/solid-client-authn-js">Solid authentication client</a>
|
||||
to interact with the server.</p>
|
||||
<p>The links here assume the server is hosted at <code>http://localhost:3000/</code>.</p>
|
||||
@ -1151,7 +1151,7 @@ but in future the plan is to also use this for account/pod management.</p>
|
||||
You can either let the server create a WebID for you in a pod,
|
||||
which will also need to be created then,
|
||||
or you can link an already existing WebID you have on an external server.</p>
|
||||
<p>In case you try to link your own WebID, you can choose if you want to be able
|
||||
<p>In case you try to link your own WebID, you can choose if you want to be able
|
||||
to use this server as your IDP for this WebID.
|
||||
If not, you can still create a pod,
|
||||
but you will not be able to direct the authentication client to this server to identify yourself.</p>
|
||||
@ -1169,7 +1169,7 @@ For example, if you choose the name <code>test</code>,
|
||||
your pod would be located at <code>http://localhost:3000/test/</code>
|
||||
and your generated WebID would be <code>http://localhost:3000/test/profile/card#me</code>.</p>
|
||||
<p>The generated name also depends on the configuration you chose for your server.
|
||||
If you are using the subdomain feature,
|
||||
If you are using the subdomain feature,
|
||||
such as being done in the <code>config/memory-subdomains.json</code> configuration,
|
||||
the generated pod URL would be <code>http://test.localhost:3000/</code>.</p>
|
||||
<h2 id="logging-in">Logging in<a class="headerlink" href="#logging-in" title="Permanent link">¶</a></h2>
|
||||
@ -1190,7 +1190,7 @@ By default, the server uses the templates found in <code>/templates/identity/ema
|
||||
but different templates can be used through configuration.</p>
|
||||
<p>These templates all make use of a JSON API exposed by the server.
|
||||
For example, when doing a GET request to <code>http://localhost:3000/idp/register/</code>
|
||||
with a JSON accept header, the following JSON is returned:
|
||||
with a JSON accept header, the following JSON is returned:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w"></span>
|
||||
@ -1216,9 +1216,9 @@ with a JSON accept header, the following JSON is returned:
|
||||
<span class="w"> </span><span class="nt">"apiVersion"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0.3"</span><span class="w"></span>
|
||||
<span class="p">}</span><span class="w"></span>
|
||||
</code></pre></div>
|
||||
The <code>required</code> and <code>optional</code> fields indicate which input fields are expected by the API.
|
||||
<p>The <code>required</code> and <code>optional</code> fields indicate which input fields are expected by the API.
|
||||
These correspond to the fields of the HTML registration page.
|
||||
To register a user, you can do a POST request with a JSON body containing the correct fields:
|
||||
To register a user, you can do a POST request with a JSON body containing the correct fields:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"test@example.com"</span><span class="p">,</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"secret"</span><span class="p">,</span><span class="w"></span>
|
||||
@ -1230,7 +1230,7 @@ To register a user, you can do a POST request with a JSON body containing the co
|
||||
<span class="w"> </span><span class="nt">"podName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"test"</span><span class="w"></span>
|
||||
<span class="p">}</span><span class="w"></span>
|
||||
</code></pre></div>
|
||||
Two fields here that are not covered on the HTML page above are <code>rootPod</code> and <code>template</code>.
|
||||
<p>Two fields here that are not covered on the HTML page above are <code>rootPod</code> and <code>template</code>.
|
||||
<code>rootPod</code> tells the server to put the pod in the root of the server instead of a location based on the <code>podName</code>.
|
||||
By default the server will reject requests where this is <code>true</code>, except during setup.
|
||||
<code>template</code> is only used by servers running the <code>config/dynamic.json</code> configuration,
|
||||
@ -1240,7 +1240,7 @@ so this value can usually be ignored.</p>
|
||||
<p>The above descriptions cover server behaviour with most default configurations,
|
||||
but just like any other feature, there are several features that can be changed
|
||||
through the imports in your configuration file.</p>
|
||||
<p>All available options can be found in
|
||||
<p>All available options can be found in
|
||||
the <a href="https://github.com/CommunitySolidServer/CommunitySolidServer/tree/main/config/identity"><code>config/identity/</code> folder</a>.
|
||||
Below we go a bit deeper into the available options</p>
|
||||
<h3 id="access">access<a class="headerlink" href="#access" title="Permanent link">¶</a></h3>
|
||||
|
||||
@ -1029,7 +1029,7 @@ The default CSS configurations use as a convention that <code>http://example.org
|
||||
has <code>http://example.org/resource.meta</code> as its description resource.</p>
|
||||
<h2 id="how-to-edit-the-metadata-of-a-resource">How to edit the metadata of a resource<a class="headerlink" href="#how-to-edit-the-metadata-of-a-resource" title="Permanent link">¶</a></h2>
|
||||
<p>Editing the metadata of a resource is performed by editing the description resource directly.
|
||||
This can only be done using <code>PATCH</code> requests
|
||||
This can only be done using <code>PATCH</code> requests
|
||||
(see <a href="#example-of-a-workflow-for-editing-a-description-resource">example workflow</a>).</p>
|
||||
<p><code>PUT</code> requests on description resources are not allowed,
|
||||
because they would replace the entire resource state,
|
||||
@ -1041,14 +1041,15 @@ Instead, the lifecycle of description resources is managed by the server.</p>
|
||||
<p>Some metadata is managed by the server and can not be modified directly, such as the last modified date.
|
||||
The CSS will throw an error (409 <code>ConflictHttpError</code>) when trying to change this protected metadata.</p>
|
||||
<h3 id="preserving-metadata">Preserving metadata<a class="headerlink" href="#preserving-metadata" title="Permanent link">¶</a></h3>
|
||||
<p><code>PUT</code> requests on a resource will reset the description resource.
|
||||
<p><code>PUT</code> requests on a resource will reset the description resource.
|
||||
There is however a way to keep the contents of description resource prior to the <code>PUT</code> request:
|
||||
adding the HTTP <code>Link</code> header targeting the description resource with <code>rel="preserve"</code>.</p>
|
||||
<p>When the resource URL is <code>http://localhost:3000/foobar</code>, preserving its description resource when updating its contents can be achieved like in the following example:</p>
|
||||
<p>When the resource URL is <code>http://localhost:3000/foobar</code>, preserving its description resource when updating its contents
|
||||
can be achieved like in the following example:</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X PUT <span class="s1">'http://localhost:3000/foobar'</span> <span class="se">\</span>
|
||||
-H <span class="s1">'Content-Type: text/turtle'</span> <span class="se">\</span>
|
||||
-H <span class="s1">'Link: <http://localhost:3000/foobar.meta>;rel="preserve"'</span> <span class="se">\</span>
|
||||
-d <span class="s2">"<ex:s> <ex:p> <ex:o>."</span>
|
||||
-d <span class="s2">"<ex:s> <ex:p> <ex:o>."</span>
|
||||
</code></pre></div>
|
||||
<h2 id="impact-on-creating-containers">Impact on creating containers<a class="headerlink" href="#impact-on-creating-containers" title="Permanent link">¶</a></h2>
|
||||
<p>When creating a container the input body is ignored
|
||||
@ -1066,10 +1067,10 @@ we first send a <code>HEAD</code> request to the resource to obtain the URL of i
|
||||
<div class="highlight"><pre><span></span><code>curl --head <span class="s1">'http://localhost:3000/foo/'</span>
|
||||
</code></pre></div>
|
||||
<p>which will produce a response with at least these headers:</p>
|
||||
<p><div class="highlight"><pre><span></span><code>HTTP/1.1 <span class="m">200</span> OK
|
||||
<div class="highlight"><pre><span></span><code>HTTP/1.1 <span class="m">200</span> OK
|
||||
Link: <http://localhost:3000/foo/.meta><span class="p">;</span> <span class="nv">rel</span><span class="o">=</span><span class="s2">"describedby"</span>
|
||||
</code></pre></div>
|
||||
Now that we have the URL of the description resource,
|
||||
<p>Now that we have the URL of the description resource,
|
||||
we create a patch for adding the inbox in the description of the resource.</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -X PATCH <span class="s1">'http://localhost:3000/foo/.meta'</span> <span class="se">\</span>
|
||||
-H <span class="s1">'Content-Type: text/n3'</span> <span class="se">\</span>
|
||||
@ -1078,9 +1079,9 @@ we create a patch for adding the inbox in the description of the resource.</p>
|
||||
<span class="s1">solid:inserts { <http://localhost:3000/foo/> <http://www.w3.org/ns/ldp#inbox> <http://localhost:3000/inbox/>. }.'</span>
|
||||
</code></pre></div>
|
||||
<p>After this update, we can verify that the inbox is added by performing a GET request to the description resource</p>
|
||||
<p><div class="highlight"><pre><span></span><code>curl <span class="s1">'http://localhost:3000/foo/.meta'</span>
|
||||
<div class="highlight"><pre><span></span><code>curl <span class="s1">'http://localhost:3000/foo/.meta'</span>
|
||||
</code></pre></div>
|
||||
With as result for the body
|
||||
<p>With as result for the body</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="k">@prefix</span><span class="w"> </span><span class="nn">dc:</span><span class="w"> </span><span class="nv"><http://purl.org/dc/terms/></span><span class="p">.</span>
|
||||
<span class="k">@prefix</span><span class="w"> </span><span class="nn">ldp:</span><span class="w"> </span><span class="nv"><http://www.w3.org/ns/ldp#></span><span class="p">.</span>
|
||||
<span class="k">@prefix</span><span class="w"> </span><span class="nn">posix:</span><span class="w"> </span><span class="nv"><http://www.w3.org/ns/posix/stat#></span><span class="p">.</span>
|
||||
@ -1089,7 +1090,7 @@ With as result for the body
|
||||
<span class="nv"><http://localhost:3000/foo/></span> <span class="kt">a</span> <span class="nn">ldp</span><span class="p">:</span><span class="nt">Container</span><span class="p">,</span> <span class="nn">ldp</span><span class="p">:</span><span class="nt">BasicContainer</span><span class="p">,</span> <span class="nn">ldp</span><span class="p">:</span><span class="nt">Resource</span><span class="p">;</span>
|
||||
<span class="nn">dc</span><span class="p">:</span><span class="nt">modified</span> <span class="s">"2022-06-09T08:17:07.000Z"</span><span class="p">^^</span><span class="nn">xsd</span><span class="p">:</span><span class="nt">dateTime</span><span class="p">;</span>
|
||||
<span class="nn">ldp</span><span class="p">:</span><span class="nt">inbox</span> <span class="nv"><http://localhost:3000/inbox/></span><span class="p">;.</span>
|
||||
</code></pre></div></p>
|
||||
</code></pre></div>
|
||||
<p>This can also be verified by sending a GET request to the subject resource itself.
|
||||
The inbox location can also be found in the Link headers.</p>
|
||||
<div class="highlight"><pre><span></span><code>curl -v <span class="s1">'http://localhost:3000/foo/'</span>
|
||||
|
||||
@ -886,12 +886,12 @@
|
||||
|
||||
|
||||
<h1 id="how-to-seed-accounts-and-pods">How to seed Accounts and Pods<a class="headerlink" href="#how-to-seed-accounts-and-pods" title="Permanent link">¶</a></h1>
|
||||
<p>If you need to seed accounts and pods,
|
||||
<p>If you need to seed accounts and pods,
|
||||
the <code>--seededPodConfigJson</code> command line option can be used
|
||||
with as value the path to a JSON file containing configurations for every required pod.
|
||||
The file needs to contain an array of JSON objects,
|
||||
with each object containing at least a <code>podName</code>, <code>email</code>, and <code>password</code> field. </p>
|
||||
<p>For example:
|
||||
The file needs to contain an array of JSON objects,
|
||||
with each object containing at least a <code>podName</code>, <code>email</code>, and <code>password</code> field.</p>
|
||||
<p>For example:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="p">[</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"podName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"example"</span><span class="p">,</span><span class="w"></span>
|
||||
@ -899,10 +899,10 @@ with each object containing at least a <code>podName</code>, <code>email</code>,
|
||||
<span class="w"> </span><span class="nt">"password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"abc123"</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="p">}</span><span class="w"></span>
|
||||
<span class="p">]</span><span class="w"></span>
|
||||
</code></pre></div></p>
|
||||
<p>You may optionally specify other parameters
|
||||
</code></pre></div>
|
||||
<p>You may optionally specify other parameters
|
||||
as described in the <a href="../identity-provider/#json-api">Identity Provider documentation</a>.</p>
|
||||
<p>For example, to set up a pod without registering the generated WebID with the Identity Provider:
|
||||
<p>For example, to set up a pod without registering the generated WebID with the Identity Provider:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="p">[</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="p">{</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="nt">"podName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"example"</span><span class="p">,</span><span class="w"></span>
|
||||
@ -912,7 +912,7 @@ as described in the <a href="../identity-provider/#json-api">Identity Provider d
|
||||
<span class="w"> </span><span class="nt">"register"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w"></span>
|
||||
<span class="w"> </span><span class="p">}</span><span class="w"></span>
|
||||
<span class="p">]</span><span class="w"></span>
|
||||
</code></pre></div></p>
|
||||
</code></pre></div>
|
||||
<p>This feature cannot be used to register pods with pre-existing WebIDs,
|
||||
which requires an interactive validation step.</p>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user