Import rules between packages: a change that breaks them is wrong even when it works.
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.jsondoesn'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'stooling/ornode/entry) in browser code,n3insolid-memo-clientand insolid'sclient/linearDataset.tsaside; - an import of a Solid client library, any
@inrupt/package, from any file butsolid's client modules andshacl's Turtle reader, tests aside, and from any file ofsolid-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.
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."
| 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.
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 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).
A deck saved as a file, or read from one (studio.md), needs no library of its own:
solidwrites Turtle with@inrupt/solid-client'ssolidDatasetAsTurtleand JSON-LD with jsonLd.ts, a few lines over the triples. It reads both withparseQuads. Turtle is read with the parser pod documents are read with: the library's, onn3, but with no triple terms; so are the profile documents a WebID names. The parser is in client/linearDataset.ts, the only file ofsolidthat may importn3. JSON-LD is read withjsonld-streaming-parser, the parser the library uses, given a document loader that loads nothing, so that reading a file never fetches a context.parseQuadsis in client/resources.ts, the only file ofsolidthat may importjsonld-streaming-parser(VENDOR_ONLY_IN). WithSOLID_CLIENT=solid-memo-client, that package'sresources.tswrites and reads Turtle withn3, and reads JSON-LD withjsonld-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, andn3to 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.tswrites JSON-LD on either client.browser'sFileExchangeport saves and opens files with what the browser has (fileExchange.ts): aBlobbehind a link withdownload, and a hidden<input type="file">. The UI never touches a file.
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.
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 (isSafeWriteUrlin 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.
- is http(s), with no query, fragment, dot segment or empty segment
(
-
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 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 (
isInFolderininstanceLayout.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 toFOREIGN_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 toPROFILE_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 thanMAX_PROFILE_DOCUMENTSof 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, toPROFILE_LIMITSon its own, and reads no more thanMAX_PROFILE_DOCUMENTSof 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 toFOREIGN_LIMITStoo. - Outside the user's storages, the reads share a budget in a page
session (
FOREIGN_READS_BUDGET,sharedReadBudgetin readLimits.ts): four timesFOREIGN_LIMITSin 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 aReadLimitErroruntil 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.
- 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 inns/and runnpm run generate(shapes.md, vocab.md). - Modules reachable from
vite.config.tsspell out.tson relative imports. Vite can load the config with Node's own loader, which needs them. Imports between packages go throughexports, with no extension. - Only
compositionwires the layers together (appUseCases.ts, and a Studio trial's trialUseCases.ts), every port, or a "none" it means, such as a trial'sNO_DEVICE.apps/web/src/main.tsxcalls@solid-memo/compositionwith 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'ssrc/style.css, the site's stylesheet, imported byapps/web/src/main.tsx, stylesui's components (none only the Studio shows) with the color roles ofsrc/palettes.css, which it imports (theme.md).- The Studio's stylesheet,
apps/studio/src/ui/studio.css, imported only byshell/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).
- Add it to the one package it belongs to
(
npm install <lib> -w @solid-memo/<package>). - If it performs I/O, put it behind a port in
packages/application/src/ports.ts, implemented in an adapter package. - Add it to the vendor table above.