@sovereignfs/create 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/create.mjs CHANGED
@@ -7,7 +7,7 @@ import { createInterface } from "readline/promises";
7
7
  // package.json
8
8
  var package_default = {
9
9
  name: "@sovereignfs/create",
10
- version: "0.4.0",
10
+ version: "0.5.0",
11
11
  type: "module",
12
12
  description: "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
13
13
  license: "AGPL-3.0-or-later",
@@ -258,6 +258,8 @@ var APP_DEPENDENCIES = {
258
258
  "react-dom": "^19.3.1"
259
259
  };
260
260
  var APP_DEV_DEPENDENCIES = {
261
+ // Makes the image's label and port from the manifest, and checks the manifest (`sovereign-manifest`).
262
+ "@sovereignfs/manifest": "^0.1.0",
261
263
  "@types/node": "^24.19.2",
262
264
  "@types/pg": "^8.23.1",
263
265
  "@types/react": "^19.3.0",
@@ -273,7 +275,8 @@ var RENAMED = {
273
275
  _dockerignore: ".dockerignore",
274
276
  "_env.example": ".env.example",
275
277
  // A published package may not carry a file called tsconfig.json.
276
- "_tsconfig.json": "tsconfig.json"
278
+ "_tsconfig.json": "tsconfig.json",
279
+ _github: ".github"
277
280
  };
278
281
  function namesOf(dir) {
279
282
  const name = path2.basename(path2.resolve(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
@@ -315,8 +318,7 @@ function appPackageJson(names) {
315
318
  build: "next build",
316
319
  start: "node .next/standalone/server.js",
317
320
  typecheck: "tsc --noEmit",
318
- "manifest:check": "node scripts/manifest.mjs",
319
- "manifest:write": "node scripts/manifest.mjs --write"
321
+ "manifest:check": "sovereign-manifest check"
320
322
  },
321
323
  dependencies: APP_DEPENDENCIES,
322
324
  devDependencies: APP_DEV_DEPENDENCIES
@@ -329,18 +331,12 @@ function appPackageJson(names) {
329
331
  async function writeApp(target, names) {
330
332
  await checkEmpty(target);
331
333
  const written = [];
332
- const replace = (text, label2) => text.replaceAll("__PREFIX__", names.prefix).replaceAll("__NAME__", names.name).replaceAll("__TITLE__", names.title).replaceAll("__MANIFEST_LABEL__", label2 ?? "");
333
- const manifestText = replace(
334
- await readFile(path2.join(TEMPLATE, "sovereign.manifest.json"), "utf8")
335
- );
336
- const label = JSON.stringify(JSON.stringify(JSON.parse(manifestText)));
334
+ const replace = (text) => text.replaceAll("__PREFIX_LOWER__", names.prefix.toLowerCase()).replaceAll("__PREFIX__", names.prefix).replaceAll("__NAME__", names.name).replaceAll("__TITLE__", names.title);
337
335
  for await (const file of walk(TEMPLATE)) {
338
- const parts = file.split(path2.sep);
339
- const last = parts.pop();
340
- const out = path2.join(...parts, RENAMED[last] ?? last);
336
+ const out = path2.join(...file.split(path2.sep).map((part) => RENAMED[part] ?? part));
341
337
  const target_ = path2.join(target, out);
342
338
  await mkdir2(path2.dirname(target_), { recursive: true });
343
- await writeFile2(target_, replace(await readFile(path2.join(TEMPLATE, file), "utf8"), label));
339
+ await writeFile2(target_, replace(await readFile(path2.join(TEMPLATE, file), "utf8")));
344
340
  written.push(out);
345
341
  }
346
342
  await writeFile2(path2.join(target, "package.json"), appPackageJson(names));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sovereignfs/create",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "description": "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
6
6
  "license": "AGPL-3.0-or-later",
@@ -1,5 +1,10 @@
1
- # This app as one image (spec/app-manifest.md §4): a process that is not root, configured by its environment alone, listening on
2
- # 3000, that applies its own migrations when it starts. `docker build -t __NAME__ .`
1
+ # This app as one image (contracts/app-manifest.md §4): a process that is not root, configured by its environment alone, listening on
2
+ # the port its manifest names, that applies its own migrations when it starts.
3
+ #
4
+ # The manifest (sovereign.manifest.json) is the one place the port is written, and the image's label is made from it, so build with the
5
+ # arguments @sovereignfs/manifest prints from it:
6
+ #
7
+ # eval "docker build $(npx sovereign-manifest docker-args) -t __NAME__ ."
3
8
 
4
9
  ARG NODE_VERSION=24
5
10
 
@@ -12,9 +17,13 @@ ENV NEXT_TELEMETRY_DISABLED=1
12
17
  RUN npm run build
13
18
 
14
19
  FROM node:${NODE_VERSION}-alpine AS run
20
+ # The port comes from the manifest, as the build argument sovereign-manifest docker-args gives. A build without it would listen where the
21
+ # instance does not look, so it stops here.
22
+ ARG PORT
23
+ RUN test -n "${PORT}" || { echo 'Build with: eval "docker build $(npx sovereign-manifest docker-args) ."' >&2; exit 1; }
15
24
  ENV NODE_ENV=production \
16
25
  NEXT_TELEMETRY_DISABLED=1 \
17
- PORT=3000 \
26
+ PORT=${PORT} \
18
27
  HOSTNAME=0.0.0.0
19
28
  WORKDIR /app
20
29
  COPY --from=build --chown=node:node /app/.next/standalone ./
@@ -22,8 +31,5 @@ COPY --from=build --chown=node:node /app/.next/static ./.next/static
22
31
  # The migrations are read from disk when the server starts, and Next does not trace them.
23
32
  COPY --from=build --chown=node:node /app/migrations ./migrations
24
33
  USER node
25
- EXPOSE 3000
34
+ EXPOSE ${PORT}
26
35
  CMD ["node", "server.js"]
27
-
28
- # What the instance reads to host this app, without pulling the image. Keep it equal to sovereign.manifest.json: `npm run manifest:check`, or `npm run manifest:write` to copy it over.
29
- LABEL io.github.sovereignfs.app-manifest=__MANIFEST_LABEL__
@@ -6,33 +6,44 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
6
6
 
7
7
  ## What is here
8
8
 
9
- | Where | What |
10
- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
11
- | `sovereign.manifest.json` | What the instance needs to know to host it: its address paths, the scopes it asks for, its port and health path |
12
- | `Dockerfile` | One image, not root, on port 3000. Its `io.github.sovereignfs.app-manifest` label is the manifest |
13
- | `app/auth/[action]/route.ts` | Sign-in, sign-out, core's back-channel logout, and core's notice that a person deleted their account |
14
- | `lib/auth.ts`, `lib/stores.ts` | The SDK's sign-in, and where it keeps sessions and refresh tokens (your database; tokens encrypted) |
15
- | `app/api/health/route.ts` | Answers 200 when the database does |
16
- | `instrumentation.ts`, `lib/migrate.ts`, `migrations/` | The app applies its own migrations when it starts, each once |
17
- | `app/page.tsx` | A page behind sign-in, using [`@sovereignfs/ui`](https://www.npmjs.com/package/@sovereignfs/ui) |
9
+ | Where | What |
10
+ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | `sovereign.manifest.json` | The manifest, the one copy: what the instance needs to know to host it (its address paths, the scopes it asks for, its port and health path) |
12
+ | `Dockerfile` | One image, not root, on the manifest's port. Its label and port are made from the manifest when it is built |
13
+ | `.github/workflows/publish.yml` | On a `vX.Y.Z` tag, builds the image for amd64 and arm64 and publishes it to `ghcr.io/<owner>/<repository>` |
14
+ | `app/auth/[action]/route.ts` | Sign-in, sign-out, core's back-channel logout, and core's notice that a person deleted their account |
15
+ | `lib/auth.ts`, `lib/stores.ts` | The SDK's sign-in, and where it keeps sessions and refresh tokens (your database; tokens encrypted) |
16
+ | `app/api/health/route.ts` | Answers 200 when the database does |
17
+ | `instrumentation.ts`, `lib/migrate.ts`, `migrations/` | The app applies its own migrations when it starts, each once |
18
+ | `app/page.tsx` | A page behind sign-in, using [`@sovereignfs/ui`](https://www.npmjs.com/package/@sovereignfs/ui) |
18
19
 
19
20
  ## Build and host it
20
21
 
22
+ The image's label (which is how an instance reads the manifest without pulling the image) and its port are made from
23
+ `sovereign.manifest.json` by [`@sovereignfs/manifest`](https://www.npmjs.com/package/@sovereignfs/manifest), so build with what it prints:
24
+
21
25
  ```bash
22
- docker build -t ghcr.io/you/__NAME__:0.1.0 .
26
+ npm install
27
+ eval "docker build $(npx sovereign-manifest docker-args) -t ghcr.io/you/__NAME__:0.1.0 ."
23
28
  docker push ghcr.io/you/__NAME__:0.1.0
24
29
  ```
25
30
 
31
+ or push a tag and let `.github/workflows/publish.yml` do it (`package.json`'s `version` must be the tag's):
32
+
33
+ ```bash
34
+ git tag v0.1.0 && git push origin v0.1.0
35
+ ```
36
+
26
37
  then, in your instance repository:
27
38
 
28
39
  ```bash
29
- ./sv app add __NAME__ --image ghcr.io/you/__NAME__:0.1.0
40
+ ./sv app add __NAME__ --image ghcr.io/you/__NAME__:0.1.0 # the name is the app's address; it may be left out, and is then the manifest's prefix
30
41
  ./sv push && ./sv deploy
31
42
  ```
32
43
 
33
- `sv` reads the manifest from the image's label, shows you the scopes it asks for, gives it its address, its database and its secrets,
34
- and registers it with core. Change `sovereign.manifest.json`, then `npm run manifest:write` to copy it into the Dockerfile, and
35
- build again; `npm run manifest:check` says whether they agree.
44
+ `sv` reads the manifest from the image's label, shows you the scopes it asks for, gives it its address, its port (as `PORT`), its database and
45
+ its secrets, and registers it with core. Change `sovereign.manifest.json` and build again; `npm run manifest:check` says whether it is
46
+ valid.
36
47
 
37
48
  Two things to know. A person is identified by `session.sub` and by nothing else. And when you add data about people, delete it in
38
49
  `onAccountDeleted` in `lib/auth.ts`, which core calls when someone deletes their account.
@@ -45,4 +56,4 @@ npm run dev
45
56
  ```
46
57
 
47
58
  See [Using the SDK](https://github.com/sovereignfs/sovereign/blob/main/docs/using-the-sdk.md) for what `sv.as(person)` can call, and
48
- [the app manifest](https://github.com/sovereignfs/sovereign/blob/main/spec/app-manifest.md) for what the instance gives and expects.
59
+ [the app manifest](https://github.com/sovereignfs/sovereign/blob/main/contracts/app-manifest.md) for what the instance gives and expects.
@@ -1,4 +1,4 @@
1
- # What the instance gives this app (spec/app-manifest.md §3), for running it on your own machine against a core you can reach.
1
+ # What the instance gives this app (contracts/app-manifest.md §3), for running it on your own machine against a core you can reach.
2
2
  # A secret may be given as NAME_FILE=/path instead of NAME=value.
3
3
  __PREFIX___URL=http://localhost:3000
4
4
  __PREFIX___CORE_URL=https://core.sovereign.local
@@ -6,4 +6,9 @@ __PREFIX___CORE_CLIENT_ID=
6
6
  __PREFIX___CORE_CLIENT_SECRET=
7
7
  __PREFIX___DB_DIALECT=postgres
8
8
  __PREFIX___POSTGRES_URL=postgres://user:password@localhost:5432/__NAME__
9
+ # The same database on the server itself, never behind a pooler: the migrations and the token lock use it. Without it, the line above is used.
10
+ __PREFIX___POSTGRES_DIRECT_URL=postgres://user:password@localhost:5432/__NAME__
11
+ # The most connections the app may hold in all (2 or more), 2 of them for the direct address. An instance sets it, and limits the app's
12
+ # database role to that number plus 2. Without it, 10.
13
+ __PREFIX___POSTGRES_POOL_MAX=10
9
14
  __PREFIX___AUTH_SECRET=change-me-to-something-long-and-random
@@ -0,0 +1,63 @@
1
+ name: Publish
2
+
3
+ # Builds this app's image when a version tag is pushed, and publishes it to GitHub's container registry as ghcr.io/<owner>/<repository>
4
+ # tagged X.Y.Z, which is where `sv app add --git` looks for it (operator-cli §4.2.1):
5
+ #
6
+ # git tag v1.0.0 && git push origin v1.0.0
7
+ #
8
+ # The image carries the manifest as its label and is built to listen on the manifest's port, both made from sovereign.manifest.json by
9
+ # @sovereignfs/manifest, so the manifest is written once.
10
+ on:
11
+ push:
12
+ tags:
13
+ - 'v*.*.*'
14
+
15
+ permissions:
16
+ contents: read
17
+ packages: write
18
+
19
+ jobs:
20
+ image:
21
+ runs-on: ubuntu-latest
22
+ steps:
23
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
24
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
25
+ with:
26
+ node-version: 24
27
+ - run: npm ci --ignore-scripts --no-audit --no-fund
28
+
29
+ # The tag names the version, so it has to be the one the package says. The image is tagged X.Y.Z, without the v.
30
+ - id: version
31
+ run: |
32
+ expected="${GITHUB_REF_NAME#v}"
33
+ actual="$(node -p "require('./package.json').version")"
34
+ if [ "$actual" != "$expected" ]; then
35
+ echo "The tag $GITHUB_REF_NAME expects version $expected, but package.json says $actual." >&2
36
+ exit 1
37
+ fi
38
+ echo "version=$expected" >> "$GITHUB_OUTPUT"
39
+
40
+ # Fails the build on a manifest an instance would refuse.
41
+ - run: npx sovereign-manifest check
42
+
43
+ - id: manifest
44
+ run: npx sovereign-manifest docker-args --format github >> "$GITHUB_OUTPUT"
45
+
46
+ - id: image
47
+ run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
48
+
49
+ - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
50
+ - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
51
+ - uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
52
+ with:
53
+ registry: ghcr.io
54
+ username: ${{ github.actor }}
55
+ password: ${{ secrets.GITHUB_TOKEN }}
56
+ - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
57
+ with:
58
+ context: .
59
+ platforms: linux/amd64,linux/arm64
60
+ push: true
61
+ tags: ${{ steps.image.outputs.name }}:${{ steps.version.outputs.version }}
62
+ labels: ${{ steps.manifest.outputs.labels }}
63
+ build-args: ${{ steps.manifest.outputs.build-args }}
@@ -1,4 +1,4 @@
1
- /** Runs once when the server starts. The app applies its own migrations before it takes a request (spec/app-manifest.md §4). */
1
+ /** Runs once when the server starts. The app applies its own migrations before it takes a request (contracts/app-manifest.md §4). */
2
2
  export async function register() {
3
3
  if (process.env.NEXT_RUNTIME === 'nodejs') {
4
4
  const { migrate } = await import('./lib/migrate');
@@ -1,7 +1,7 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
 
3
3
  /**
4
- * Reads a setting the instance gives this app (spec/app-manifest.md §3). A secret arrives as a file named by `NAME_FILE`, so it is
4
+ * Reads a setting the instance gives this app (contracts/app-manifest.md §3). A secret arrives as a file named by `NAME_FILE`, so it is
5
5
  * never in the process list or a log; the plain `NAME` is read as well, for running it on your own machine.
6
6
  */
7
7
  export function setting(name: string): string | undefined {
@@ -1,10 +1,41 @@
1
1
  import { Pool } from 'pg';
2
- import { required } from './config';
2
+ import { required, setting } from './config';
3
3
 
4
4
  let pool: Pool | undefined;
5
+ let direct: Pool | undefined;
5
6
 
6
- /** The app's own database, as its own role. One pool for the process, made when it is first used so that building needs none. */
7
+ /** What of the pool goes to `directDb()`: a lock held across a call needs a connection of its own, and it counts against the same limit. */
8
+ const DIRECT_MAX = 2;
9
+
10
+ /** How many connections the app may hold in all: what the instance gives it, whose limit for the app's database role is set from the same number, or 10. */
11
+ function poolMax(): number {
12
+ const given = Number(process.env.__PREFIX___POSTGRES_POOL_MAX);
13
+ return Number.isInteger(given) && given >= 2 ? given : 10;
14
+ }
15
+
16
+ /**
17
+ * The app's own database, as its own role, for everything that is safe when each statement may run on a different server connection: this
18
+ * is the address an instance may put behind a transaction pooler (`database.pooling` in the manifest). One pool for the process, made when
19
+ * it is first used so that building needs none.
20
+ */
7
21
  export function db(): Pool {
8
- pool ??= new Pool({ connectionString: required('__PREFIX___POSTGRES_URL'), max: 10 });
22
+ pool ??= new Pool({
23
+ connectionString: required('__PREFIX___POSTGRES_URL'),
24
+ max: Math.max(poolMax() - DIRECT_MAX, 2),
25
+ });
9
26
  return pool;
10
27
  }
28
+
29
+ /**
30
+ * The same database on the server itself, never through a pooler, for what needs one connection throughout: the advisory locks of the
31
+ * migrations and of the token refresh. An instance made before the direct address existed does not give it, and has no pooler, so the
32
+ * pooled address is the server and is used instead.
33
+ */
34
+ export function directDb(): Pool {
35
+ direct ??= new Pool({
36
+ connectionString:
37
+ setting('__PREFIX___POSTGRES_DIRECT_URL') ?? required('__PREFIX___POSTGRES_URL'),
38
+ max: DIRECT_MAX,
39
+ });
40
+ return direct;
41
+ }
@@ -1,13 +1,14 @@
1
1
  import { readdirSync, readFileSync } from 'node:fs';
2
2
  import path from 'node:path';
3
- import { db } from './db';
3
+ import { directDb } from './db';
4
4
 
5
5
  /**
6
- * Applies the files in `migrations/`, in name order, each once (spec/app-manifest.md §4: an app applies its own migrations when it
7
- * starts, and is safe to start again). One advisory lock holds a second copy of the app back until the first has finished.
6
+ * Applies the files in `migrations/`, in name order, each once (contracts/app-manifest.md §4: an app applies its own migrations when it
7
+ * starts, and is safe to start again). One advisory lock holds a second copy of the app back until the first has finished. It is a session
8
+ * lock, and a session is one connection, so all of it runs on the direct address, never behind a pooler.
8
9
  */
9
10
  export async function migrate(): Promise<void> {
10
- const client = await db().connect();
11
+ const client = await directDb().connect();
11
12
  try {
12
13
  await client.query('SELECT pg_advisory_lock(hashtext($1))', ['__NAME__-migrations']);
13
14
  await client.query(
@@ -1,5 +1,5 @@
1
1
  import type { SessionStore, StoredRecord, TokenStore } from '@sovereignfs/sdk';
2
- import { db } from './db';
2
+ import { db, directDb } from './db';
3
3
  import { fingerprint, open, seal } from './crypto';
4
4
 
5
5
  /** The SDK's sessions, in the app's database (sdk §9.1). Nothing is returned after its expiry. */
@@ -83,7 +83,8 @@ export const tokenStore: TokenStore = {
83
83
  },
84
84
 
85
85
  async lock(sub, work) {
86
- const client = await db().connect();
86
+ // A session lock, held across a call to core: on the direct address, which a pooler is never in front of.
87
+ const client = await directDb().connect();
87
88
  try {
88
89
  await client.query('SELECT pg_advisory_lock(hashtext($1))', [`__NAME__-token:${sub}`]);
89
90
  return await work();
@@ -1,6 +1,6 @@
1
1
  {
2
- "manifest": 1,
3
- "prefix": "__PREFIX__",
2
+ "manifest": 2,
3
+ "prefix": "__PREFIX_LOWER__",
4
4
  "name": "__TITLE__",
5
5
  "description": "Notes, as a starting point for an app on a Sovereign instance",
6
6
  "port": 3000,
@@ -13,7 +13,7 @@
13
13
  "accountDeleted": "/auth/account-deleted",
14
14
  "scopes": ["openid", "profile", "email", "offline_access"]
15
15
  },
16
- "database": true,
16
+ "database": { "pooling": "transaction" },
17
17
  "generate": ["__PREFIX___AUTH_SECRET"],
18
18
  "core": ">=0.49.0 <1.0.0"
19
19
  }
@@ -1,25 +0,0 @@
1
- // The manifest label in the Dockerfile is what an instance reads to host this app, so it must say what sovereign.manifest.json says.
2
- // node scripts/manifest.mjs checks that it does
3
- // node scripts/manifest.mjs --write copies the manifest into the label
4
- import { readFileSync, writeFileSync } from 'node:fs';
5
-
6
- const PREFIX = 'LABEL io.github.sovereignfs.app-manifest=';
7
- const manifest = JSON.parse(readFileSync('sovereign.manifest.json', 'utf8'));
8
- // A Dockerfile quotes a value as JSON quotes a string, so the label is the manifest as a JSON string of JSON.
9
- const wanted = `${PREFIX}${JSON.stringify(JSON.stringify(manifest))}`;
10
- const lines = readFileSync('Dockerfile', 'utf8').split('\n');
11
- const at = lines.findIndex((line) => line.startsWith(PREFIX));
12
-
13
- if (process.argv.includes('--write')) {
14
- if (at === -1) lines.push(wanted);
15
- else lines[at] = wanted;
16
- writeFileSync('Dockerfile', lines.join('\n'));
17
- console.log('Wrote the manifest label.');
18
- } else if (lines[at] !== wanted) {
19
- console.error(
20
- 'The manifest label in the Dockerfile differs from sovereign.manifest.json. Run: npm run manifest:write',
21
- );
22
- process.exit(1);
23
- } else {
24
- console.log('The manifest label matches.');
25
- }