From 4d05fe4315e282d6e1ec19af01b185cb21cab29c Mon Sep 17 00:00:00 2001 From: Joachim Van Herwegen Date: Tue, 7 Nov 2023 09:07:44 +0100 Subject: [PATCH] docs: Explain the patching store in-depth * docs: Explain the patching store in-depth * docs: Fix language in patching documentation Co-authored-by: Ted Thibodeau Jr --------- Co-authored-by: Ted Thibodeau Jr --- .../features/protocol/overview.md | 1 + .../features/protocol/patching.md | 75 +++++++++++++++++++ documentation/mkdocs.yml | 1 + 3 files changed, 77 insertions(+) create mode 100644 documentation/markdown/architecture/features/protocol/patching.md diff --git a/documentation/markdown/architecture/features/protocol/overview.md b/documentation/markdown/architecture/features/protocol/overview.md index d1b0d5443..405565cdc 100644 --- a/documentation/markdown/architecture/features/protocol/overview.md +++ b/documentation/markdown/architecture/features/protocol/overview.md @@ -29,3 +29,4 @@ Below are sections that go deeper into the specific steps. * [How input gets parsed and output gets returned](parsing.md) * [How authentication and authorization work](authorization.md) * [What the `ResourceStore` looks like](resource-store.md) +* [How resources can be modified](patching.md) diff --git a/documentation/markdown/architecture/features/protocol/patching.md b/documentation/markdown/architecture/features/protocol/patching.md new file mode 100644 index 000000000..6d36adafc --- /dev/null +++ b/documentation/markdown/architecture/features/protocol/patching.md @@ -0,0 +1,75 @@ +# Modifying resources + +As described [here](resource-store.md#patchingstore), +there is a generic solution for modifying resources as a result of PATCH requests. +It consists of doing the following steps: + +1. Convert the stored resource to a stream of quad objects (a/k/a, a quad stream). +2. Read the quad stream and ingest the quads into an [N3.js Store](https://github.com/rdfjs/N3.js#storing). +3. If the target resource is metadata, ensure that the immutable triples don't get changed. +4. Apply the patch to the quad store. +5. Convert the quad store to a quad stream. +6. Convert the quad stream back to the original media type of the resource. + +The architecture is described more in-depth below. + +```mermaid +flowchart LR + PatchingStore("ResourceStore_Patching
ResourceStore") + PatchingStore --> PatchHandler("PatchHandler
RepresentationPatchHandler") + PatchHandler --> Patchers("
WaterfallHandler") + Patchers --> ConvertingPatcher("
ConvertingPatcher") + ConvertingPatcher --> RdfPatcher("RdfPatcher
RdfPatcher") +``` + +```mermaid +flowchart LR + RdfPatcher("RdfPatcher
RdfPatcher") + RdfPatcher --> RDFStore("PatchHandler_RDFStore
WaterfallHandler") + RDFStore --> RDFStoreArgs + + subgraph RDFStoreArgs[" "] + Immutable("PatchHandler_ImmutableMetadata
ImmutableMetadataPatcher") + RDF("PatchHandler_RDF
WaterfallHandler") + Immutable --> RDF + end + + RDF --> RDFArgs + + subgraph RDFArgs[" "] + direction LR + N3("
N3Patcher") + SPARQL("
SparqlUpdatePatcher") + end +``` + +The `PatchingStore` is the entry point. +It first checks whether the [next store](resource-store.md) supports modifying resources. +Only if this is not the case will it start the generic patching solution by calling its `PatchHandler`. + +The `RepresentationPatchHandler` calls the source `ResourceStore` +to get a data stream representing the current state of the resource. +It feeds that stream as input into a `RepresentationPatcher`, +and then writes the result back to the store. + +Similarly to the way accessing resources is done through a stack of `ResourceStore`s, +patching is done through a stack of `RepresentationPatcher`s, +each performing a step in the patching process. + +The `ConvertingPatcher` is responsible for converting the original resource to a stream of quad objects, +and converting the modified result back to the original type. +By converting to quads, all other relevant classes can act independently of the actual RDF serialization type. +For similar reasons, the `RdfPatcher` converts the quad stream to an [`N3.js` Store](https://github.com/rdfjs/N3.js#storing) +so the next patchers do not have to worry about handling stream data +and have access to the entire resource in memory. + +The `ImmutableMetadataPatcher` keeps track of a list of triples that cannot be modified +in the metadata of a resource. +For example, it is not possible to modify the metadata to indicate whether it is +a [storage root](https://solidproject.org/TR/2022/protocol-20221231#storage-resource). +The `ImmutableMetadataPatcher` tracks all these triples before and after a metadata resource is modified, +and throws an error if one is modified. +If the target resource is not metadata but a standard resource, this class will be skipped. + +Finally, either the `N3Patcher` or the `SparqlUpdatePatcher` will be called, +depending on the type of patch that is requested. diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index afa440ea9..45b53fed7 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -102,6 +102,7 @@ nav: - Parsing: architecture/features/protocol/parsing.md - Authorization: architecture/features/protocol/authorization.md - Resource Store: architecture/features/protocol/resource-store.md + - Modifying resources: architecture/features/protocol/patching.md - Account management: - Overview: architecture/features/accounts/overview.md - Controls: architecture/features/accounts/controls.md