Skip to content

Latest commit

 

History

History
507 lines (458 loc) · 30.1 KB

boundaries.md

File metadata and controls

507 lines (458 loc) · 30.1 KB

Boundaries

Import rules between packages: a change that breaks them is wrong even when it works.

Enforcement

npm run check:boundaries (checkBoundaries.ts) runs in npm run check and in CI. It reads every workspace package's imports and fails on:

  • a relative import that leaves its package;
  • a workspace package the layer or the importing file may not use (the table below);
  • a static import of a package that may only be loaded lazily;
  • an entry point the importer may not use;
  • an import of a package the importer's package.json doesn't declare (npm hoists it to the root, where it would still resolve and type-check);
  • a node-only import (node:*, n3, @solid-memo/turtle, @solid-memo/site, any package's tooling/ or node/ entry) in browser code, n3 in solid-memo-client and in solid's client/linearDataset.ts aside;
  • an import of a Solid client library, any @inrupt/ package, from any file but solid's client modules and shacl's Turtle reader, tests aside, and from any file of solid-memo-client, tests included (below);
  • an import of @inrupt/solid-client's access control from any file but the public-read grant's, tests aside (below).

Test files follow their subject's rules and, like the vitest configs, may use the root package.json's shared test tooling. A package's Vite and Vitest configs may import the root's shared setup: vitest.shared.ts and the Solid client switch, scripts/solidClient.ts.

An example

A screen in ui may import application (the table below):

// packages/ui/src/ui/DeckListContainer.tsx
import type { UseCases } from "@solid-memo/application/useCases";

It may not import an adapter, such as the guest's pod in solid:

// packages/ui/src/ui/SomeScreen.tsx
import { createLocalPod } from "@solid-memo/solid/localPod";

The check names the file and rule per problem, and fails:

packages/ui/src/ui/SomeScreen.tsx: @solid-memo/ui may not import @solid-memo/solid.
packages/ui/src/ui/SomeScreen.tsx: imports @solid-memo/solid, which package.json does not declare.
2 boundary problem(s).

The fix is a use case on UseCases, with composition wiring the adapter behind its port. A rule that allows only some files names them; importing the composition root anywhere in apps/web but its entry point gives:

apps/web/src/App.tsx: only files matching /^src\/main\.tsx$/ may import @solid-memo/composition.

With no problem, the check prints "Every package keeps to its boundaries."

Layers

Package May import Only from
turtle —
markdown —
vocab turtle turtle: tooling/ only
site vocab, turtle, markdown vocab: tooling/root alone (the repository's folders); turtle for the docs' index (markdown.md); markdown to render the docs (markdown.md)
domain vocab
application domain, vocab
shacl domain, vocab, turtle, markdown turtle, markdown: node/ only
solid application, domain, vocab, shacl
browser application, domain
ui application, domain, vocab, markdown markdown: src/ui/ only
composition application, domain, vocab, solid, browser
web application, domain, vocab, ui, composition, studio, site composition, and studio with a dynamic import(): src/main.tsx only; site: vite.config.ts (the site's build, which renders the docs) and tests only
studio application, domain, vocab, ui
e2e-pod application, domain, vocab, solid, solid-memo-client solid-memo-client: signedInClient.ts only, which signs in to a Linked Web Storage server
solid-memo-client solid No package the app is made of imports it: the build puts its modules in place of solid's client modules (below)
e2e-journeys ui, studio ui and studio: harness/strings.ts only, for their messages

Browser code is the src/ of markdown, vocab, domain, application, shacl, solid, browser, composition, ui, web, studio and solid-memo-client.

Vendor libraries

Each library is a dependency of, and allowed in, only the packages listed:

Library Package Notes
@inrupt/solid-client, @inrupt/solid-client-authn-browser solid src/client/ only (below); shacl uses @inrupt/solid-client in src/turtleDocument.ts only, to parse shapes; its access control only in src/client/access.ts (below)
@inrupt/solid-client-authn-core solid tests only: the sign-in library's own DPoP proof, for authFetch's tests
@tanstack/react-query, preact ui, web, studio components; in web, main.tsx, which renders the page, and App.tsx, the page; in studio, its screens
@fontsource/*, @fontsource-variable/* ui, site in ui, src/style.css only; in site, @fontsource-variable/fredoka in src/drawDiagrams.ts only, to embed Fredoka in the diagrams (markdown.md)
rdf-validate-shacl, rdf-validate-datatype shacl src/engine.ts only, loaded lazily; rdf-validate-datatype for its registry of datatype checks (validation.md)
markdown-it, markdown-it-cjk-friendly markdown src/parse.ts only; the package's API is its own types, never markdown-it's tokens (markdown.md)
n3 turtle, the node tooling of shacl, e2e-pod, solid-memo-client and solid in e2e-pod, the server contract and the tests; in solid-memo-client, in the browser too; in solid, src/client/linearDataset.ts only, in the browser too: the Turtle parser Inrupt's client is given, and the terms of a dataset's quads (below)
jsonld-streaming-parser, oauth4webapi solid-memo-client the JSON-LD parser; Solid-OIDC sign-in
fake-indexeddb browser, composition, solid-memo-client tests only: IndexedDB in node, for the guest's pod's store and the sign-in session
@playwright/test e2e-journeys drives the built app in Chromium, Firefox and WebKit; the harness talks to the Solid server with its request API
axe-core e2e-journeys pages/App.ts only, which loads its build into the page: checks the screen each journey step ends on for accessibility (testing.md)
mermaid, playwright site src/drawDiagrams.ts only, both node-only in the check: Mermaid draws the docs' diagrams in Chromium, which playwright starts (markdown.md); development tools, not shipped (vendor-code.md)

The Solid client libraries

The rest of the code calls the Solid client libraries through modules of the app's own, in packages/solid/src/client/, so another library could take their place there alone (vendor-code.md):

Module What it has
interface.ts the types the other modules take and give, HttpError, the sign-in client's interface and the grant's type; it imports no library
rdf.ts the data model: datasets and their subjects, read and built, many subjects set or removed in one pass
linearDataset.ts a document read into a dataset in one pass, where the library takes time in the square of its size, a dataset's quads made one by one, where the library spreads a subject's into one call, a property's literals and blank nodes as terms in one pass, where the library joins its list at each language and datatype, and the Turtle parser it and parseQuads read with, on n3, for resources.ts and rdf.ts alone
readLimits.ts the limits a read of a release, or of an instance's documents outside the user's own pod, takes in, the bounds every read keeps on a Turtle text's base and prefix declarations, on the long IRIs the parser resolves, on how deep it nests and on the length of each term, the fetch that holds a body to them, the tally that holds its triples to them, and the parts a parser is given a text in, to be stopped between them; it imports no library
linkHeader.ts the bound on the Link and WAC-Allow headers of a response, dropped past it before any parser reads them; it imports no library
resources.ts reading and writing pods, conditional reads and writes among them, and the Turtle and JSON-LD parsers
sparqlUpdate.ts the SPARQL Update bodies of the app's PATCH requests; it imports no library
inrupt.ts the library's objects behind the interface's types, for the other modules alone
session.ts the sign-in client, on @inrupt/solid-client-authn-browser
providerRedirect.ts the sessionStorage key session.ts marks the tab under while it waits on the identity provider, kept apart so it stays whichever client is in place; it imports no library
access.ts the public-read grant (below)

shacl may not import solid, so it reads a shape's Turtle with a module of its own, turtleDocument.ts, as pod documents are read.

A second implementation of rdf.ts, resources.ts, session.ts, access.ts and shacl's turtleDocument.ts, with no Inrupt library, is in packages/solid-memo-client/. Inrupt's is the default; with SOLID_CLIENT=solid-memo-client, the Vite plugin in scripts/solidClient.ts resolves every import of those modules to that package's module of the same name. It imports no @inrupt/ package, tests included, and no package imports it (VENDOR_NEVER_IN and the layer table). solid-memo-client.md says what it's built on and how it differs.

npm run check:boundaries (checkBoundaries.ts, VENDOR_ONLY_IN) lets only these files but interface.ts, outside tests, import any @inrupt/ package, with any import: named, a namespace, a subpath such as @inrupt/solid-client/universal, or a dynamic import(). Such an import elsewhere is reported once, not again by the access-control rule. Tests mock the client modules, not the libraries, and the client modules' own tests run the contract in src/testing/contract/, which another implementation must pass too (vendor-code.md).

Files without a vendor library

A deck saved as a file, or read from one (studio.md), needs no library of its own:

  • solid writes Turtle with @inrupt/solid-client's solidDatasetAsTurtle and JSON-LD with jsonLd.ts, a few lines over the triples. It reads both with parseQuads. Turtle is read with the parser pod documents are read with: the library's, on n3, but with no triple terms; so are the profile documents a WebID names. The parser is in client/linearDataset.ts, the only file of solid that may import n3. JSON-LD is read with jsonld-streaming-parser, the parser the library uses, given a document loader that loads nothing, so that reading a file never fetches a context. parseQuads is in client/resources.ts, the only file of solid that may import jsonld-streaming-parser (VENDOR_ONLY_IN). With SOLID_CLIENT=solid-memo-client, that package's resources.ts writes and reads Turtle with n3, and reads JSON-LD with jsonld-streaming-parser, also with a document loader that loads nothing, and is its only file that may import it. Either client tells the JSON-LD parser to read no RDF-star, and n3 to read no Turtle triple terms. A Turtle parse fails, too, at a triple that holds one, as an annotation or a reifier gives, which the option lets through. jsonLd.ts writes JSON-LD on either client.
  • browser's FileExchange port saves and opens files with what the browser has (fileExchange.ts): a Blob behind a link with download, and a hidden <input type="file">. The UI never touches a file.

Access control

The app changes access in two places only: a published release becomes readable by everyone (studio.md), and so does a public type index the app creates, never one already there that it adopts (data-model.md). Only two adapters make that write: the ReleasePublisher port's, solidReleasePublisher.ts, and the InstanceRepository port's, solidInstanceRepository.ts. Each makes it with the grant it's given, through accessControlFetch.ts, which lets the grant write only that document's own ACL or ACR. client/access.ts has @inrupt/solid-client's universalAccess.setPublicAccess, read only, for the document, writing its own ACL (Web Access Control) or ACR (Access Control Policies). That fetch refuses another origin, or a write of anything but <document>.acl or <document>.acr, whatever the server names as the document's access control. No folder's access control changes. With SOLID_CLIENT=solid-memo-client, the grant is solid-memo-client's access.ts, which writes the document's own ACL or ACR with fetch and n3 (solid-memo-client.md).

npm run check:boundaries (checkBoundaries.ts, VENDOR_ONLY_FROM) lets only client/access.ts, outside tests, import @inrupt/solid-client's access control (universalAccess, the acp_* modules, the ACL functions) or all of the library (import * as). Another client module may import the rest of the library, never its access control. At run time, the pod fence refuses any other module's ACL or ACR write.

The pod fence

Every pod adapter's one fetch (appUseCases.ts) passes two fences before the guest's pod or the network:

  • The pod fence (podFence.ts, createPodFence) lets reads (GET, HEAD, OPTIONS) through and refuses other methods before they're sent (writeRefused), unless the address is safe to write (isSafeWriteUrl in instanceLayout.ts). Such an address, as sent:

    • is http(s), with no query, fragment, dot segment or empty segment (//);
    • has nothing encoded a server might read as a step elsewhere or another name: a slash, backslash, percent sign, letter or digit, or an overlong byte;
    • isn't an access control or metadata resource (.acl, .acr, .meta, in any case).

    It holds for every write and sender (addresses come from pod data anyone may have written). Where the instance is known, adapters still check which documents its code may write (data-model.md); the type index, the profile link, registrations, releases and copies are written outside instances.

  • The write fence (writeFence.ts) keeps an instance being moved or copied read-only (guest-mode.md).

The fences check the address a request asks for, not one a server redirects it to. Behind them, the fetch that carries the user's credentials follows no redirect, so a write never reaches an address the pod fence didn't check. A write that redirects is refused (redirectRefused), and a read that redirects is sent again as no one (authentication.md). That fetch also refuses any address, read or write, that the proof of the user's login would name another server for (credentialsRefused).

A read of another server, as the user or as no one, has deadlines (readDeadline.ts, withReadDeadline). The server has 10 seconds to start to answer, and 10 seconds for each next part of the body. A read of a server that isn't the user's pod has two minutes for the whole read as well, its body included. That holds for a read as no one, and for every read as the user outside their storages and the folders they entered on this page: an instance registered elsewhere, its meta.ttl, its deck documents and its releases among them. Past any of them, the read is aborted and fails with podNoAnswer, which the app tries again (style.md). Without them, a server that never answers, or answers and then sends its body slowly or not at all, keeps a screen loading for good. A read of the user's own pod, a document or a folder, takes as long in all as its body keeps coming, so a large document on a slow connection still downloads. The reads that find the user's storages, their profile among them, have the two minutes, since every other read as the user waits on them. While their storages can't be found, every read has the two minutes. A catalog may name a deck's documents on any server, and the data check and the statistics wait on reading them. The check gives the documents outside the instance's folder one minute in all, every read of them included, and names those it couldn't read; every other read ends at its own deadline (validation.md). The statistics leave a deck whose documents fail to be read out until a later read. Two minutes is far longer than the largest release in the library takes to download. The deck library holds a read of a release added from a link to two minutes of its own too, its check left out (deck-library.md). The guest's pod, in this browser, has no deadline. A write has none either: one cut off might still be saved, and only its answer says whether it was. Adding an answer to the log is the one exception: it's added whole, so one given up is added again later (data-model.md).

The release publisher alone gets a second fetch for its access control, through the same fences, whose pod fence lets a document's own ACL or ACR (<document>.acl, <document>.acr) through, never a folder's. It's used only inside the publisher's check, which allows the release's two (Access control). A Studio trial's fetch allows only GET and HEAD (studio.md).

The credential gate

The login's fetch sends the user's access token to any address it's given. So the adapters that read and write an instance's data get another fetch (appUseCases.ts). They're the decks, cards, review states, answers, preferences, palettes, the digest, the drafts, the instance check and its repairs, the graph, a deck's export, a Studio trial, and deleting an instance's data. Behind the pod fence that fetch passes the credential gate (ownPodGate.ts, createOwnPodGate):

  • In the user's own pod a request goes on as the user, a read or a write. The user's own pod is the storages their profile names and the instances they registered in a type index in the profile's own places (below). On this page it's also a storage they entered by hand and the folder they moved a guest's study into. Each counts with what's in it (isInFolder in instanceLayout.ts). For an instance in someone else's pod, only its own folder counts. It goes through the same fences and login fetch as any pod request, so it follows no redirect either. A registered instance outside the user's storages is anyone's to make, and another app may register it, so what's read there is held to FOREIGN_LIMITS, which match a release's (deck-library.md). The storages and the folders entered on this page, a storage entered by hand trusted like one the profile names, are read as the user with no limits on size. The reads of the profile's documents are the exception, since they're made at every sign-in. The WebID document is held to PROFILE_LIMITS, a wide margin over the few triples a profile holds. The reads of it, each under that limit, are these: the storage lookup, the identity provider's lookup, the check of a session's issuer, the account's name, the developer tools' view of it, and the type index lookup. The provider's lookup is read as no one, at login and sign-in. The issuer check is read as no one too, on every load with a session. The type index lookup runs at every load, as the app lists the user's instances. The storage lookup holds the documents the WebID document names as more of the profile to them all together, and reads no more than MAX_PROFILE_DOCUMENTS of them. One outside the user's own storages, or the WebID's own pod when none is found, isn't read and doesn't count. The type index lookup holds each of them, and the preferences file, to PROFILE_LIMITS on its own, and reads no more than MAX_PROFILE_DOCUMENTS of them too. A WebID document past them fails the sign-in and the lookup, and a further document past them, or past that count, is left out.
  • Anywhere else a read is sent as no one (credentials: "omit"), and a write is refused before it's sent (writeOutsidePod). A catalog may name a deck's documents on any server (data-model.md), and what such a document says of itself never makes it writable. Such a read is held to FOREIGN_LIMITS too.
  • Outside the user's storages, the reads share a budget in a page session (FOREIGN_READS_BUDGET, sharedReadBudget in readLimits.ts): four times FOREIGN_LIMITS in total, on top of the limits on each read. A catalog may list a thousand decks, each with two documents as large as a release. The reads as no one share one budget; the reads in a registered instance elsewhere have one for each server, so reads anywhere else never spend it. Those reads share a total over all their servers (INSTANCE_READS_TOTAL) and one allowance for reading again, since the app follows up to a thousand of them in a type index. As with releases read from a link (deck-library.md), a document counts once, by its largest read, and reading it again comes out of an allowance of its own (FOREIGN_REREADS) while that lasts. Past the budget, such a read fails with a ReadLimitError until the page is loaded again, without asking the server. Only reads count: a write to a registered instance goes out whatever is spent. The storages and the folders entered on this page aren't part of it.
  • A read past its limits fails with a ReadLimitError. So does a document the app reads into a dataset whose Turtle text has too many bases, a base that's too long or not plain, or too many prefixes, with limits or with none. So does one with an IRI longer than 512 characters that's relative or may hold a . or .. segment. That holds for a deck's documents, a folder's listing and a profile alike. The document's own address counts toward a base's length, so a document of the user's at an address longer than 512 characters can't be read. Nor can one another app wrote with a base that has a . or .. segment, unless it's a relative path with no colon, such as <./>: the parser removes those as it resolves it. The library's own reads of access controls aren't bounded so; they're the user's own.
  • The folders are asked once a WebID and kept. The page asks for them again when it adds or removes one: a storage entered, an instance made, registered or deleted, a guest's study moved. An address outside them has them asked again at most once a minute, for an instance registered elsewhere. A failed ask fails the request.
  • A guest's pod is this browser's, routed before the gate. Logged out, nothing is the user's. Only a guest's own instance may name a deck's document there, and a read as no one never goes there.

The profile, the storages, the type indexes and the instances' registrations are read and written through the pod fetch, without the gate. They're how the gate finds the user's own pod, and an instance added by its address isn't registered until it's read. So is copying an instance, and publishing a release; the releases a catalog links, which the Studio lists for any instance it shows, are read through the gate as the instance's data is. A release already at the address being published to, or one being made public, is read under RELEASE_LIMITS, since the instance may be on another server. Its access control, read as it's made public, is read under ACCESS_CONTROL_LIMITS on its bytes, its triples, their characters and its declarations before the grant parses it, and held to MAX_ACCESS_CONTROL_SUBJECTS subjects. These limits are small, because the grant's library takes time that grows with the square of an access control's subjects. The subject limit holds as well for a folder's access control the server falls back to, which may be the user's own. So a release under a folder shared through more rules than that can't be made public: the grant fails. A read the grant makes of the release, or of a folder above it, is held to RELEASE_LIMITS. Once a request gets no answer or goes past its limits, the grant fails. An instance's meta.ttl is read through the pod fetch too, under FOREIGN_LIMITS, since a folder added by its address is read as soon as it's added. A release a draft follows is read through createOwnPodFetch, which asks the same folders (studio.md). A new draft copies a release or a deck's cards into the instance, and a move or copy of cards copies a deck's cards and review states into another of its decks (studio.md). So each is read as no one outside the instance's pod: in neither the instance nor a storage of the user's that holds it.

For the profile and the type indexes, the profile's own places stand in for the gate (profilePlaces.ts): the WebID's origin, its document's, and the storages the WebID document names. A document the profile links (rdfs:seeAlso, foaf:isPrimaryTopicOf, pim:preferencesFile) is read as the user only in one of the user's own storages, or in the WebID's own pod when none is found. When that pod would be the whole origin, as for a WebID document at its root, no such document is read. One anywhere else isn't read at all, nor taken as part of the profile. A storage such a document names counts only inside a storage already found. A type index outside them may be someone else's, so the app takes it as no index at all: it reads nothing in it, writes nothing there, and offers to create the user's own, as for a missing index. Nothing such an index registers is the user's, so no instance in it joins the folders the gate sends credentials to. A profile whose index is on another server names that storage (pim:storage) in the WebID document for the app to use it. Of several links to an index, the app takes one in those places. These places say where the profile may be read, not where the app may point it. One server may keep many users' pods on the WebID's origin, so the app takes a type index, linked or entered by its address, only when it's in one of the user's own storages (data-model.md). It reads the preferences file and writes a link into an extended profile only there too. When no storage can be found, it still reads the indexes in those places, but writes only to one in the WebID's own pod. It writes to none when that pod would be the whole origin, or when the lookup failed.

Further rules

  • UI components never import ports or adapters; they get UseCases, or the slices they use, as a prop.
  • Generated files (packages/vocab/src/*.generated.ts) are never edited by hand: change the vocabulary or the shapes in ns/ and run npm run generate (shapes.md, vocab.md).
  • Modules reachable from vite.config.ts spell out .ts on relative imports. Vite can load the config with Node's own loader, which needs them. Imports between packages go through exports, with no extension.
  • Only composition wires the layers together (appUseCases.ts, and a Studio trial's trialUseCases.ts), every port, or a "none" it means, such as a trial's NO_DEVICE. apps/web/src/main.tsx calls @solid-memo/composition with the site's own values (its name, where it's served, the build's), and renders its components.
  • The Studio is loaded lazily (the table), a chunk of its own that learners never download (studio.md).
  • ui's src/style.css, the site's stylesheet, imported by apps/web/src/main.tsx, styles ui's components (none only the Studio shows) with the color roles of src/palettes.css, which it imports (theme.md).
  • The Studio's stylesheet, apps/studio/src/ui/studio.css, imported only by shell/StudioShell.tsx (a relative import inside the package), so it ships in the Studio's chunk. Its rules hold only under :root[data-surface="studio"] (studio.md).

Adding a dependency

  1. Add it to the one package it belongs to (npm install <lib> -w @solid-memo/<package>).
  2. If it performs I/O, put it behind a port in packages/application/src/ports.ts, implemented in an adapter package.
  3. Add it to the vendor table above.