Zayin/Signage
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases 4 Wiki Activity

Compare commits

base: Zayin/Signage:fix/release-module-assets
Branches Tags
Zayin/Signage:main Zayin/Signage:stage0/signage-production-readiness Zayin/Signage:release/0.1.4 Zayin/Signage:fix/manual-release-workflow Zayin/Signage:fix/release-module-assets Zayin/Signage:chore/release-0.1.3 Zayin/Signage:feat/external-signage-integration
Zayin/Signage:v0.1.4 Zayin/Signage:v0.1.3 Zayin/Signage:v0.1.2 Zayin/Signage:v0.1.1
..
compare: Zayin/Signage:776540ff78f22685205609dfa6b5f0bac42c2881
Branches Tags
Zayin/Signage:stage0/signage-production-readiness Zayin/Signage:main Zayin/Signage:release/0.1.4 Zayin/Signage:fix/manual-release-workflow Zayin/Signage:fix/release-module-assets Zayin/Signage:chore/release-0.1.3 Zayin/Signage:feat/external-signage-integration
Zayin/Signage:v0.1.4 Zayin/Signage:v0.1.3 Zayin/Signage:v0.1.2 Zayin/Signage:v0.1.1
2 Commits
fix/release-module-assets .. 776540ff78
Author SHA1 Message Date
ekklesiaandClaude Opus 5.5 776540ff78 fix(display): define the display-server messages once, in src/shared 
The display controller and the viewer routes each described the
heartbeat their own way and disagreed about one thing: the display sent
null for "nothing to report", and the route accepted only a missing
field. Every heartbeat from a screen showing a native image was refused
with a 400. The roster therefore marked working screens Offline 90 s
after they opened, and never recorded offlineReady or cachedAssetCount.

src/shared/display-protocol.ts now defines every message between a
display and the server:
- viewer session request and response;
- heartbeat request and response;
- channel state;
- the realtime display payload.

Both halves import it. Its rules: a nullable field accepts null
explicitly, an absent field means "not reported", and an unknown field
is ignored, so a newer display is never refused by an older server.

- The routes parse with the shared parsers, and a refusal names the
  field with Signage's sanitized code.
- The server's channel state extends the wire type, so a field the
  display relies on cannot drift without a compile error.
- The display builds its heartbeat as the shared type, and reads its
  registration with the shared parser instead of casting it.
- Test stubs that described server responses more loosely than the
  server sends them (no viewerName, no stale, partial media) now match
  the real responses and are typed as the protocol.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
 2026-10-05 18:32:34 -05:00
ekklesiaandClaude Opus 5.5 7483d7cbbe test(display): run the real display controller against the real viewer routes 
Every display test answered the controller with a hand-written stub, and
every viewer test called the service with a hand-written object, so
neither side was ever tested against the other. In production every
heartbeat was refused with a 400.

This suite answers the real controller's requests with the real viewer
route handlers over the in-memory store. The routes gain an optional
store factory for that; production still uses the module database.

Fails today: POST /viewers/:viewerId/heartbeat -> 400
SIGNAGE_INVALID_REQUEST, because the display sends
reportedContributionId: null and the route accepts only a missing field.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
 2026-10-05 18:28:59 -05:00
48 changed files with 178 additions and 6396 deletions
Expand all files Collapse all files
.gitea/workflows/ci.yml
-253
View File
@@ -1,253 +0,0 @@
name: CI
# Signage is a standalone repository: every job installs it with --frozen-lockfile from its own
# pnpm-lock.yaml and takes Ekklesia's module-development packages (@ekklesia/*) from Ekklesia's
# public package registry (.npmrc; platform ADRs 0053 and 0054). Only the integration job fetches
# Core source: one immutable commit through the pinned Gitea pull ref in ci/platform.env, used as the
# generic deployment harness and image source, never as a workspace dependency.
#
# The same trust rules as the platform's own CI (docs/development/security.md there):
# * every action is pinned by a full commit SHA;
# * every checkout sets `persist-credentials: false`, and nothing in this workflow pushes;
# * no repository, organization, or instance secret is referenced;
# * there is no `pull_request_target`;
# * the self-hosted runner executes trusted, reviewed code only.
#
# The server is Gitea 1.27, which honours `concurrency` cancellation; `permissions` and
# `timeout-minutes` are declared so the workflow is correct wherever they are enforced.
# Artifact actions v3 are deliberate: Gitea implements that protocol, while v4 refuses non-GitHub
# servers. This workflow never publishes or mutates a release; publishing is a separate manual gate.
on:
pull_request:
push:
branches:
- main
permissions:
contents: read
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
lint:
name: lint
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Check out repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
# Nothing here pushes, so the job token is never needed after checkout and must not be left
# in .git/config for a later step to read.
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
# pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
# .npmrc: no token, and no Ekklesia checkout.
- name: Install (frozen lockfile)
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
- name: Lint
run: pnpm lint
- name: Check that CI cleans up every stack it starts
run: |
bash ci/check-cleanup.sh
python3 -m unittest ci/test_release_assets.py
typecheck:
name: typecheck
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Check out repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
# Nothing here pushes, so the job token is never needed after checkout and must not be left
# in .git/config for a later step to read.
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
# pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
# .npmrc: no token, and no Ekklesia checkout.
- name: Install (frozen lockfile)
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
- name: Typecheck the server, browser, and browser-test projects
run: pnpm typecheck
test:
name: test
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Check out repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
# Nothing here pushes, so the job token is never needed after checkout and must not be left
# in .git/config for a later step to read.
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
# pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
# .npmrc: no token, and no Ekklesia checkout.
- name: Install (frozen lockfile)
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
- name: Unit, browser, and display contract tests
run: pnpm test
build:
name: build
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Check out repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
# Nothing here pushes, so the job token is never needed after checkout and must not be left
# in .git/config for a later step to read.
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
# pnpm at exactly the `packageManager` version, and @ekklesia/* from the public registry named in
# .npmrc: no token, and no Ekklesia checkout.
- name: Install (frozen lockfile)
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
- name: Build the server and both browser artifacts
run: pnpm build
# The built package and its migrations, read the way the platform reads them, with only the
# published SDK parsers (scripts/validate-module.mjs says what only Ekklesia itself can check).
- name: Validate the built module and its migrations
run: pnpm validate
# Build the canonical pair once. Integration downloads these exact bytes and may not repackage.
package:
name: package
runs-on: ubuntu-latest
timeout-minutes: 20
outputs:
sha256: ${{ steps.canonical.outputs.sha256 }}
steps:
- name: Check out repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
- name: Install (frozen lockfile)
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
- name: Build the canonical Module Package pair
id: canonical
run: bash ci/package.sh
- name: Hand the canonical pair to its consumers
uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
with:
name: signage-module-package
path: build/module-package/
if-no-files-found: error
retention-days: 30
# The real linux-x64-glibc Signage Module Package inside Ekklesia, end to end. The pinned platform
# builds one generic image with no bundled module source, verifies and installs Signage into
# persistent module storage, applies its migrations, and drives its split-origin Dashboard and
# kiosk display in real browsers. It then checks process restart, container recreation, lifecycle
# disable/re-enable, removal, and reinstall against the same database and package.
integration:
name: integration
needs:
- test
- build
- package
runs-on: ubuntu-latest
timeout-minutes: 45
env:
DOCKER_BUILDKIT: "1"
EXPECTED_PACKAGE_SHA256: ${{ needs.package.outputs.sha256 }}
# Names this job's stacks, so its final step removes exactly these (the platform's
# scripts/lib/ci-project.sh).
EKKLESIA_CI_JOB_KEY: signage-integration
steps:
- name: Check out repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
- name: Install (frozen lockfile)
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
- name: Receive the canonical Module Package pair
uses: actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b # v3.1.0-node20
with:
name: signage-module-package
path: build/module-package/
- name: Fetch the pinned Ekklesia integration harness
run: bash ci/fetch-platform.sh
# A job the runner killed (cancelled, or past the runner's own time limit) never ran its
# cleanup. Anything a CI job left on this shared daemon more than three hours ago goes first.
- name: Sweep stale CI stacks from the runner
run: bash build/platform/scripts/ci-sweep.sh --stale
- name: Install and run the prebuilt external Signage package
run: bash ci/integration.sh
# Whatever happened above, this job's own stacks do not outlive it. If the first step failed,
# nothing was started.
- name: Remove this job's CI stacks
if: always()
run: |
if [ -f build/platform/scripts/ci-sweep.sh ]; then
bash build/platform/scripts/ci-sweep.sh --job
fi
.gitea/workflows/publish-release.yml
-180
View File
@@ -1,180 +0,0 @@
name: Publish Signage Release
# Builds, proves, and publishes one Signage release. This is deliberately separate from CI: only an
# operator's workflow_dispatch on a selected branch can start it. The normal release ref is main.
# Every local gate, including the full external-package integration and ADR 0055 redistribution
# verification, finishes before the release/tag is created or an existing release is touched.
on:
workflow_dispatch:
inputs:
version:
description: The Signage version to publish, equal to package and module metadata.
required: true
type: string
permissions:
contents: read
# Never cancel a publication part way, and never run two at once. A rerun safely resumes an
# identical partial upload, but refuses a tag, release, or asset that differs from this run.
concurrency:
group: publish-signage-release
cancel-in-progress: false
jobs:
release-gate:
name: release gate
runs-on: ubuntu-latest
timeout-minutes: 75
outputs:
sha256: ${{ steps.canonical.outputs.sha256 }}
env:
DOCKER_BUILDKIT: "1"
EKKLESIA_CI_JOB_KEY: signage-publish-release
RELEASE_VERSION: ${{ inputs.version }}
RELEASE_TAG: v${{ inputs.version }}
RELEASE_REVISION: ${{ github.sha }}
steps:
- name: Check out the operator-selected revision
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: Set up Node.js at the repository's version
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version-file: .node-version
- name: Install the reviewed build and release tooling
run: |
corepack enable
corepack install
pnpm install --frozen-lockfile
# Match Core's manual publisher: releases come only from reviewed main. The source version is
# checked before the expensive gate, and the selected commit remains the immutable tag target.
- name: Validate requested version and selected revision
run: |
[[ "$GITHUB_REF" == refs/heads/main ]] || {
echo "publish: select main; got $GITHUB_REF" >&2
exit 1
}
[[ "$RELEASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
echo "publish: version must be X.Y.Z; got $RELEASE_VERSION" >&2
exit 1
}
[[ "$RELEASE_REVISION" =~ ^[0-9a-f]{40}$ ]]
[[ "$(git rev-parse HEAD)" == "$RELEASE_REVISION" ]]
[[ -z "$(git status --porcelain)" ]]
node --input-type=module -e '
import { readFileSync } from "node:fs";
const requested = process.env.RELEASE_VERSION;
const packageVersion = JSON.parse(readFileSync("package.json", "utf8")).version;
const moduleVersion = JSON.parse(readFileSync("ekklesia.module.json", "utf8")).version;
if (packageVersion !== requested || moduleVersion !== requested) {
console.error(`publish: requested ${requested}, package ${packageVersion}, module ${moduleVersion}`);
process.exit(1);
}
console.log(`publish: source metadata agrees on ${requested}`);
'
# This is the only package build in the workflow. Every later step consumes this directory.
- name: Build the canonical Module Package pair once
id: canonical
run: bash ci/package.sh build/release-assets
- name: Verify the canonical Module Package
env:
EXPECTED_PACKAGE_SHA256: ${{ steps.canonical.outputs.sha256 }}
run: |
pnpm validate
python3 ci/release-assets.py verify-package \
build/release-assets "$RELEASE_TAG" "$RELEASE_REVISION"
- name: Fetch the pinned Ekklesia integration harness
run: bash ci/fetch-platform.sh
- name: Sweep stale CI stacks from the runner
run: bash build/platform/scripts/ci-sweep.sh --stale
- name: Run full integration with the exact release package
env:
EXPECTED_PACKAGE_SHA256: ${{ steps.canonical.outputs.sha256 }}
run: bash ci/integration.sh "$GITHUB_WORKSPACE/build/release-assets"
- name: Remove this publication's CI stacks
if: always()
run: |
if [ -f build/platform/scripts/ci-sweep.sh ]; then
bash build/platform/scripts/ci-sweep.sh --job
fi
- name: Build and verify required redistribution assets
env:
EXPECTED_PACKAGE_SHA256: ${{ steps.canonical.outputs.sha256 }}
run: |
package="$(find build/release-assets -maxdepth 1 -type f -name 'signage-*-linux-x64-glibc.tar.gz')"
pnpm exec ekklesia-corresponding-source acquire \
--package "$package" --cache "$RUNNER_TEMP/signage-corresponding-sources"
pnpm exec ekklesia-corresponding-source build \
--package "$package" --cache "$RUNNER_TEMP/signage-corresponding-sources" \
--out build/release-assets
source="${package%.tar.gz}-corresponding-source.tar.gz"
metadata="${package%.tar.gz}.redistribution.json"
pnpm exec ekklesia-corresponding-source verify \
--package "$package" --source "$source" --metadata "$metadata"
python3 ci/release-assets.py verify \
build/release-assets "$RELEASE_TAG" "$RELEASE_REVISION"
# The write-authorized job receives only the completely proven bundle. Artifact actions v3
# are required by Gitea; v4 refuses servers other than github.com.
- name: Hand the proven release bundle to the publisher
uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
with:
name: signage-release-assets
path: build/release-assets/
if-no-files-found: error
retention-days: 90
publish:
name: publish
needs: release-gate
if: github.ref == 'refs/heads/main'
permissions:
contents: write
runs-on: ubuntu-latest
timeout-minutes: 15
env:
EXPECTED_PACKAGE_SHA256: ${{ needs.release-gate.outputs.sha256 }}
RELEASE_VERSION: ${{ inputs.version }}
RELEASE_TAG: v${{ inputs.version }}
RELEASE_REVISION: ${{ github.sha }}
steps:
# The checked-out helper is the same reviewed revision the gate proved. Credentials are not
# persisted; the automatic token is exposed only to the final API call below.
- name: Check out the proven revision
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: Receive the proven release bundle
uses: actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b # v3.1.0-node20
with:
name: signage-release-assets
path: build/release-assets/
- name: Recheck the received release bundle
run: |
python3 ci/release-assets.py verify \
build/release-assets "$RELEASE_TAG" "$RELEASE_REVISION"
# Only this final step can mutate Gitea. It creates v<version> at the selected commit and a
# prerelease if absent, then uploads the already-tested bytes. A rerun resumes only identical
# state. Every asset is read back without Authorization and checked byte for byte.
- name: Create the release and publish the exact tested assets
env:
GITHUB_TOKEN: ${{ github.token }}
run: |
python3 ci/release-assets.py publish \
build/release-assets "$RELEASE_TAG" "$RELEASE_REVISION"
.gitignore
-3
View File
@@ -1,9 +1,6 @@
node_modules/
.pnpm-store/
dist/
.turbo/
coverage/
build/
__pycache__/
*.log
.DS_Store
.node-version
-1
View File
@@ -1 +0,0 @@
24.18.0
.npmrc
-3
View File
@@ -1,3 +0,0 @@
# Ekklesia's module-development packages (@ekklesia/*) come from Ekklesia's public package registry
# (platform ADRs 0053 and 0054). Reading needs no account and no token; never put a credential here.
@ekklesia:registry=https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/
LICENSE
-661
View File
@@ -1,661 +0,0 @@
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU Affero General Public License is a free, copyleft license for
software and other kinds of works, specifically designed to ensure
cooperation with the community in the case of network server software.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
our General Public Licenses are intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
Developers that use our General Public Licenses protect your rights
with two steps: (1) assert copyright on the software, and (2) offer
you this License which gives you legal permission to copy, distribute
and/or modify the software.
A secondary benefit of defending all users' freedom is that
improvements made in alternate versions of the program, if they
receive widespread use, become available for other developers to
incorporate. Many developers of free software are heartened and
encouraged by the resulting cooperation. However, in the case of
software used on network servers, this result may fail to come about.
The GNU General Public License permits making a modified version and
letting the public access it on a server without ever releasing its
source code to the public.
The GNU Affero General Public License is designed specifically to
ensure that, in such cases, the modified source code becomes available
to the community. It requires the operator of a network server to
provide the source code of the modified version running there to the
users of that server. Therefore, public use of a modified version, on
a publicly accessible server, gives the public access to the source
code of the modified version.
An older license, called the Affero General Public License and
published by Affero, was designed to accomplish similar goals. This is
a different license, not a version of the Affero GPL, but Affero has
released a new version of the Affero GPL which permits relicensing under
this license.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU Affero General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Remote Network Interaction; Use with the GNU General Public License.
Notwithstanding any other provision of this License, if you modify the
Program, your modified version must prominently offer all users
interacting with it remotely through a computer network (if your version
supports such interaction) an opportunity to receive the Corresponding
Source of your version by providing access to the Corresponding Source
from a network server at no charge, through some standard or customary
means of facilitating copying of software. This Corresponding Source
shall include the Corresponding Source for any work covered by version 3
of the GNU General Public License that is incorporated pursuant to the
following paragraph.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the work with which it is combined will remain governed by version
3 of the GNU General Public License.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU Affero General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU Affero General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU Affero General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU Affero General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If your software can interact with users remotely through a computer
network, you should also make sure that it provides a way for users to
get its source. For example, if your program is a web application, its
interface could display a "Source" link that leads users to an archive
of the code. There are many ways you could offer source, and different
solutions will be better for different programs; see section 13 for the
specific requirements.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU AGPL, see
<https://www.gnu.org/licenses/>.
README.md
+44 -50
View File
@@ -12,14 +12,13 @@ Ekklesia and vendors none of its SDKs.
- Module id: `signage`
- Package: `@ekklesia/signage`
- Manifest version: 8, with the Module Database ABI v1 (`database: { abi: 1 }`)
- Manifest version: 7
## Status
Version 0.1.3 is feature-complete for its declared scope, and Signage has run in production since
0.1.1. What exists today:
Version 0.1.1 is feature-complete for its declared scope and unreleased. What exists today:
- The module package, manifest (v8), four capabilities, six permissions, ten operator settings, and
- The module package, manifest (v7), four capabilities, six permissions, ten operator settings, and
one logical storage bucket.
- Eleven tables and a single initial migration, declared non-destructive.
- Native image ingest: one image per streamed request, 25 MiB, content-addressed, with display and
@@ -35,10 +34,10 @@ Version 0.1.3 is feature-complete for its declared scope, and Signage has run in
renderers mounted as browser contributions, the built-in "Content unavailable" slate, deliberate
blackout, and offline continuation from this display's own persisted state.
No cutover from the legacy Announcements container has happened or is planned by this repository.
Video, audio, MQTT, Home Assistant, Companion, and a notification outbox are out of scope; so is
any content module — Signage ships with no announcements, scripture, or trivia, and cannot render
any until one is installed.
Nothing here is deployed, and no cutover from the legacy Announcements container has happened or is
planned by this repository. Video, audio, MQTT, Home Assistant, Companion, and a notification outbox
are out of scope; so is any content module — Signage ships with no announcements, scripture, or
trivia, and cannot render any until one is installed.
### Offline cold start is not yet possible
@@ -51,71 +50,66 @@ Mounting requires an authenticated module descriptor, and Core does not yet cach
cold start depends on a Core-provided authorized offline display descriptor or lease; until that
exists, this module does not claim it. See ADR 0006.
## Developing Signage
## Developing against Ekklesia
Signage builds and tests on its own. You need no Ekklesia checkout and no Ekklesia account:
- **Node.js** in the range `engines.node` declares (`>=24.11.0 <25`); `.node-version` names the
version CI uses.
- **pnpm** at the version `packageManager` pins, through Corepack (`corepack enable`).
Signage is developed **inside the authoritative Ekklesia workspace**, checked out at the path it will
eventually be installed at:
```bash
git clone <this repository> signage
cd signage
corepack enable
pnpm install --frozen-lockfile
git clone <ekklesia> ekklesia
git clone <this repository> ekklesia/modules/signage
cd ekklesia
pnpm install
```
Ekklesia's module-development packages (`@ekklesia/module-sdk`, `@ekklesia/module-database`,
`@ekklesia/module-ui-sdk`, `@ekklesia/ui`, `@ekklesia/design-tokens`, `@ekklesia/module-ui-build`,
`@ekklesia/module-pack`, `@ekklesia/typescript-config`) come from Ekklesia's public package registry.
The committed `.npmrc` points the `@ekklesia` scope at it, and reading it needs **no token** and no
login (platform ADRs 0053 and 0054); never add a credential to that file. Everything else comes from
the public npm registry. `package.json` takes the Ekklesia packages as `^0.2.0` ranges, except
`@ekklesia/module-pack`, which is pinned exactly; `pnpm-lock.yaml` pins every package's exact version
and integrity, so always install with `--frozen-lockfile` unless you mean to change a dependency.
`modules/*` is an Ekklesia workspace glob, so the checkout is picked up with no registry edit,
no second copy of Ekklesia, and no vendored SDK. `@ekklesia/module-sdk`, `@ekklesia/module-ui-sdk`,
`@ekklesia/design-tokens`, `@ekklesia/ui`, and `@ekklesia/module-ui-build` all resolve through the
workspace as `workspace:*` dependencies.
`pnpm-workspace.yaml` holds this repository's own pnpm settings: it allows esbuild's install script,
exempts exactly the Ekklesia package train in the lockfile from pnpm's minimum release age, and keeps
one narrowly scoped advisory override. It does not make Signage part of any other workspace.
Two consequences worth knowing:
Signage requires Ekklesia 0.2: manifest version 8 and the Module Database ABI v1 (platform ADR 0050).
It reaches PostgreSQL only through the ABI v1 executor the platform hands it, with its own Drizzle
tables and the module-side adapter from `@ekklesia/module-database/drizzle`. Core receives SQL text,
bound values, and plain schema metadata, never a Drizzle object.
- Ekklesia uses a shared workspace lockfile, so installing here writes an importer entry for
`modules/signage` into Ekklesia's `pnpm-lock.yaml`. That entry belongs to whoever maintains the
Ekklesia checkout; it is not committed from this repository.
- Signage requires the Ekklesia platform prerequisites for shared design tokens, module stylesheets,
browser contributions, bounded streaming request bodies, and display offline code
(ADRs 0039–0043). An Ekklesia checkout without them cannot build or validate this module.
### Commands
Run from the **Ekklesia repository root**:
```bash
pnpm lint # Biome, with this repository's biome.json
pnpm typecheck # node, browser, and browser-test projects
pnpm test # unit, browser-artifact, and display contract tests (vitest.config.ts)
pnpm build # tsc, then the canonical module UI build of the primary and display artifacts
pnpm validate # after build: the built package and its migrations, as the platform reads them
pnpm --filter @ekklesia/signage build # tsc + the canonical module UI build
pnpm --filter @ekklesia/signage test # unit and browser-artifact tests
pnpm --filter @ekklesia/signage typecheck # node, browser, and browser-test projects
pnpm --filter @ekklesia/signage lint
pnpm boundaries # four-layer boundary enforcement
pnpm modules:validate # static manifest, entrypoint, and schema validation
pnpm migrations:validate # migration journal, policy, ordering, and checksums
pnpm verify # the full Docker-free gate
```
CI runs exactly these, from a clean checkout.
Signage's tests are its own: `pnpm test` here runs `vitest` against this package's `vitest.config.ts`,
which includes `.test.tsx` as well as `.test.ts`. The workspace-root config includes only `.test.ts`,
so a browser test added here without that config would be silently skipped.
`pnpm validate` uses only the published SDK parsers. It cannot check what only an Ekklesia
installation knows: compatibility with that installation, other installed modules' capabilities and
dependencies, or a migration's checksum against a database's applied history. Ekklesia checks those
when Signage is installed.
Never run a migration against a persistent database while developing this module. Signage reads no
environment variable, constructs no database client, configures no object storage, hardcodes no
Ekklesia URL, opens no socket of its own, and applies no migration: every one of those reaches it
Never run `pnpm migrations:apply` against a persistent database while developing this module. Signage
reads no environment variable, constructs no database client, configures no object storage, hardcodes
no Ekklesia URL, opens no socket of its own, and applies no migration: every one of those reaches it
through the host.
### Changing the schema
```bash
pnpm migration:generate # drizzle-kit, into drizzle/
pnpm --filter @ekklesia/signage migration:generate # drizzle-kit, into drizzle/
```
`tests/schema.test.ts` pins the checksum of the generated SQL, so a regenerated migration fails the
suite until the pin is updated deliberately. `drizzle/meta/_ekklesia.json` declares the migration
non-destructive: `tests/schema.test.ts` asserts it, and Ekklesia's own migration validation enforces
it when Signage is packaged and installed.
non-destructive; `pnpm migrations:validate` enforces that.
### Verifying what only a browser can show
biome.json
-34
View File
@@ -1,34 +0,0 @@
{
"$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
"files": {
"includes": [
"**",
"!**/.pnpm-store",
"!**/.turbo",
"!**/build",
"!**/coverage",
"!**/dist",
"!**/node_modules",
"!pnpm-lock.yaml"
]
},
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2,
"lineWidth": 100
},
"linter": {
"enabled": true,
"rules": {
"preset": "recommended"
}
},
"javascript": {
"formatter": {
"quoteStyle": "double",
"semicolons": "always",
"trailingCommas": "all"
}
}
}
ci/check-cleanup.sh
-100
View File
@@ -1,100 +0,0 @@
#!/usr/bin/env bash
# Checks that Signage's CI cleans up every stack it starts, even when the runner kills a job (the
# platform's rule: docs/development/security.md, "Disposable stacks never outlive their job").
#
# bash ci/check-cleanup.sh
#
# The `integration` job is the one that starts Docker stacks. It must have its own
# EKKLESIA_CI_JOB_KEY, sweep stale CI stacks before it starts anything, and remove its own in a final
# `if: always()` step. The pinned platform smoke owns and labels every image and container.
set -Eeuo pipefail
root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
workflow="$root/.gitea/workflows/ci.yml"
publish_workflow="$root/.gitea/workflows/publish-release.yml"
failures=0
check() {
if eval "$1"; then
echo "ok $2"
else
echo "FAIL $2"
failures=$((failures + 1))
fi
}
# The integration job's lines, from its key to the next job (or the end of the file).
job="$(awk '/^ integration:$/ { inside = 1; print; next } inside && /^ [a-z][a-z-]*:$/ { exit } inside { print }' "$workflow")"
line_of() { grep -n -F -- "$1" <<<"$job" | head -1 | cut -d: -f1 || true; }
stale="$(line_of 'ci-sweep.sh --stale')"
run="$(line_of 'bash ci/integration.sh')"
own="$(line_of 'ci-sweep.sh --job')"
last_step="$(grep -n -- " - name:" <<<"$job" | tail -1 | cut -d: -f1 || true)"
check '[[ -n "$job" ]]' "the workflow has an integration job"
check '! grep -q "if: false" <<<"$job"' "the integration job is enabled"
check 'grep -q "EKKLESIA_CI_JOB_KEY:" <<<"$job"' "the integration job names its stacks with its own key"
check '[[ -n "$stale" && -n "$run" ]] && ((stale < run))' "it sweeps stale CI stacks before it starts anything"
check '[[ -n "$own" && -n "$run" ]] && ((own > run)) && ((own > last_step))' \
"its last step removes its own stacks"
check 'sed -n "${last_step},\$p" <<<"$job" | grep -q "if: always()"' "that last step always runs"
check 'grep -q "EKKLESIA_SMOKE_MODULE_RELEASE_DIR" "$root/ci/integration.sh" && grep -q "bash scripts/smoke-deploy.sh" "$root/ci/integration.sh"' \
"the integration delegates its external package to the platform smoke"
check 'grep -Eq "^EKKLESIA_PLATFORM_REF=refs/(pull/[0-9]+/head|heads/main)$" "$root/ci/platform.env" && grep -Eq "^EKKLESIA_PLATFORM_COMMIT=[0-9a-f]{40}$" "$root/ci/platform.env"' \
"the platform harness is pinned by full ref and commit"
check 'grep -q "rev-parse refs/remotes/pinned" "$root/ci/fetch-platform.sh" && grep -q "does not resolve to EKKLESIA_PLATFORM_COMMIT" "$root/ci/fetch-platform.sh"' \
"the fetch verifies that the pinned ref resolves to the pinned commit"
# Normal CI builds the canonical archive once and hands those exact bytes to integration through a
# Gitea Actions v3 artifact. It must contain no release trigger, permission, or mutation path.
package_job="$(awk '/^ package:$/ { inside = 1; print; next } inside && /^ [a-z][a-z-]*:$/ { exit } inside { print }' "$workflow")"
check 'grep -q "pull_request:" "$workflow" && grep -q "push:" "$workflow"' \
"normal CI still runs for pull requests and main pushes"
check '! grep -q "workflow_dispatch:" "$workflow" && ! grep -q "tags:" "$workflow"' \
"normal CI has no manual-publish or tag trigger"
check '! grep -q "contents: write" "$workflow" && ! grep -q "github.token" "$workflow"' \
"normal CI has no release-specific permission or token"
check '! grep -q "release-assets.py publish" "$workflow" && ! grep -q "ekklesia-corresponding-source" "$workflow"' \
"normal CI cannot publish or prepare release assets"
check 'grep -q "bash ci/package.sh" <<<"$package_job" && grep -q "actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de" <<<"$package_job"' \
"the package job builds and transfers one canonical artifact"
check 'grep -q "actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b" <<<"$job" && ! grep -Eq "ci/package.sh|ekklesia-pack-module" <<<"$job"' \
"integration downloads that artifact and never rebuilds it"
check 'grep -q "needs.package.outputs.sha256" <<<"$job" && grep -q "GITHUB_OUTPUT" "$root/ci/package.sh"' \
"integration binds the downloaded bytes to the package job's digest"
# Publishing is an explicit operator action. One job validates its dispatch input and selected ref,
# builds the package exactly once, integration-tests that directory, prepares redistribution files,
# and only then gives the same directory to the Gitea publisher.
gate_job="$(awk '/^ release-gate:$/ { inside = 1; print; next } inside && /^ [a-z][a-z-]*:$/ { exit } inside { print }' "$publish_workflow")"
publish_job="$(awk '/^ publish:$/ { inside = 1; print; next } inside && /^ [a-z][a-z-]*:$/ { exit } inside { print }' "$publish_workflow")"
check 'grep -q "workflow_dispatch:" "$publish_workflow" && ! grep -q "pull_request:" "$publish_workflow" && ! grep -q "push:" "$publish_workflow"' \
"publishing is workflow_dispatch only and cannot run for a PR or push"
check 'grep -q "inputs:" "$publish_workflow" && grep -q " version:" "$publish_workflow" && grep -q "required: true" "$publish_workflow"' \
"manual publishing requires an explicit version input"
check 'grep -q "refs/heads/main" <<<"$gate_job" && grep -q "packageVersion.*requested" <<<"$gate_job" && grep -q "moduleVersion.*requested" <<<"$gate_job"' \
"the publish gate requires selected main and validates both source versions"
check '[[ "$(grep -c "bash ci/package.sh" "$publish_workflow")" -eq 1 ]]' \
"the publish workflow builds the canonical Module Package exactly once"
check 'grep -q "ci/integration.sh.*build/release-assets" <<<"$gate_job" && grep -q "name: signage-release-assets" <<<"$gate_job" && grep -q "name: signage-release-assets" <<<"$publish_job" && grep -q "release-assets.py publish" <<<"$publish_job"' \
"integration proves the package handed unchanged to the publisher"
check 'grep -q "EXPECTED_PACKAGE_SHA256:.*steps.canonical.outputs.sha256" <<<"$gate_job" && grep -q "EXPECTED_PACKAGE_SHA256:.*needs.release-gate.outputs.sha256" <<<"$publish_job"' \
"the publish gate binds consumers to the canonical package digest"
check 'grep -q "ekklesia-corresponding-source verify" <<<"$gate_job" && grep -q "needs: release-gate" <<<"$publish_job"' \
"corresponding-source verification finishes before the publishing job"
check 'grep -q "GITHUB_TOKEN:.*github.token" <<<"$publish_job" && grep -q "contents: write" <<<"$publish_job" && ! grep -q "contents: write" <<<"$gate_job"' \
"only the final manual publishing job receives release write authority"
# The manual workflow also owns a Docker integration stack, so it follows the same cleanup rule.
publish_stale="$(grep -n -F -- 'ci-sweep.sh --stale' <<<"$gate_job" | cut -d: -f1 || true)"
publish_run="$(grep -n -F -- 'bash ci/integration.sh' <<<"$gate_job" | cut -d: -f1 || true)"
publish_own="$(grep -n -F -- 'ci-sweep.sh --job' <<<"$gate_job" | cut -d: -f1 || true)"
check '[[ -n "$publish_stale" && -n "$publish_run" ]] && ((publish_stale < publish_run))' \
"manual publishing sweeps stale stacks before integration"
check '[[ -n "$publish_own" && -n "$publish_run" ]] && ((publish_own > publish_run))' \
"manual publishing always has a post-integration cleanup step"
((failures == 0)) || {
echo "check-cleanup: ${failures} check(s) failed." >&2
exit 1
}
ci/display-scenarios
-7
View File
@@ -1,7 +0,0 @@
# The platform's display-device scenarios this repository's CI runs against Signage, one per line
# (scripts/lib/deploy-smoke-display.mjs in the pinned platform). Pairing a kiosk and restarting it on
# the same profile always run first. A change that makes another scenario pass adds it here.
two-pages
session-blip
stream-failure
stream-recycle
ci/fetch-platform.sh
-39
View File
@@ -1,39 +0,0 @@
#!/usr/bin/env bash
# Fetches the exact Ekklesia source revision Signage's external-package integration runs against.
# The ref is fetched only to make the pinned object reachable; the checkout is always by full SHA.
set -Eeuo pipefail
root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
out="$root/build/platform"
fail() {
echo "fetch-platform: $*" >&2
exit 1
}
(($# == 0)) || fail "this command takes no arguments."
pin() {
local value
value="$(sed -n "s/^$1=//p" "$root/ci/platform.env")"
[[ -n "$value" ]] || fail "ci/platform.env has no $1."
printf '%s' "$value"
}
repository="$(pin EKKLESIA_PLATFORM_REPOSITORY)"
ref="$(pin EKKLESIA_PLATFORM_REF)"
commit="$(pin EKKLESIA_PLATFORM_COMMIT)"
[[ "$commit" =~ ^[0-9a-f]{40}$ ]] || fail "EKKLESIA_PLATFORM_COMMIT must be a full commit SHA."
[[ "$ref" == refs/* ]] || fail "EKKLESIA_PLATFORM_REF must be a full Git ref."
rm -rf "$out"
mkdir -p "$out"
git -C "$out" init --quiet
git -C "$out" remote add origin "$repository"
git -C "$out" fetch --quiet --no-tags --depth=1 origin "+${ref}:refs/remotes/pinned" ||
fail "cannot fetch the pinned platform ref."
[[ "$(git -C "$out" rev-parse refs/remotes/pinned)" == "$commit" ]] ||
fail "the pinned ref does not resolve to EKKLESIA_PLATFORM_COMMIT."
git -C "$out" -c advice.detachedHead=false checkout --quiet --detach "$commit"
rm -rf "$out/.git"
echo "fetch-platform: Ekklesia ${commit}"
ci/integration.sh
-55
View File
@@ -1,55 +0,0 @@
#!/usr/bin/env bash
# Gives the canonical linux-x64-glibc Module Package pair from the package job to the pinned
# platform's generic deployment smoke. The platform image contains no Signage source:
# its verifier extracts the package into installation-owned module storage before migrations,
# discovery, browser UI/display checks, restart, container recreation, disable/re-enable, removal,
# and reinstall are exercised against disposable PostgreSQL and object-storage services.
#
# bash ci/package.sh
# bash ci/fetch-platform.sh
# bash ci/integration.sh
set -Eeuo pipefail
root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
platform="$root/build/platform"
release="${1:-$root/build/module-package}"
[[ -f "$platform/scripts/smoke-deploy.sh" ]] || {
echo "integration: run bash ci/fetch-platform.sh first." >&2
exit 1
}
mapfile -t archives < <(find "$release" -maxdepth 1 -type f -name 'signage-*-linux-x64-glibc.tar.gz' -print)
[[ "${#archives[@]}" -eq 1 ]] || {
echo "integration: expected exactly one prebuilt Module Package archive." >&2
exit 1
}
archive="${archives[0]}"
checksum="$archive.sha256"
[[ -f "$checksum" ]] || {
echo "integration: missing $(basename "$checksum")." >&2
exit 1
}
(cd "$release" && sha256sum --check --strict "$(basename "$checksum")")
digest="$(sha256sum "$archive" | cut -d' ' -f1)"
if [[ -n "${EXPECTED_PACKAGE_SHA256:-}" && "$digest" != "$EXPECTED_PACKAGE_SHA256" ]]; then
echo "integration: prebuilt package sha256 $digest differs from the package job's $EXPECTED_PACKAGE_SHA256." >&2
exit 1
fi
scenarios="$(sed -e 's/#.*//' -e '/^[[:space:]]*$/d' "$root/ci/display-scenarios" | tr '\n' ' ')"
[[ -n "${scenarios// /}" ]] || {
echo "integration: ci/display-scenarios lists no scenario." >&2
exit 1
}
echo "integration: consuming prebuilt $(basename "$archive"); scenarios: ${scenarios}"
cd "$platform"
EKKLESIA_SMOKE_TOPOLOGY=split \
EKKLESIA_SMOKE_MODULE_RELEASE_DIR="$release" \
EKKLESIA_SMOKE_MODULE_ID=signage \
EKKLESIA_SMOKE_MODULE_PROBE_PATH=/api/v1/modules/signage/channel-groups \
EKKLESIA_SMOKE_DISPLAY_DEVICE=1 \
EKKLESIA_SMOKE_DISPLAY_SCENARIOS="$scenarios" \
EKKLESIA_SMOKE_WATCH_MS=120000 \
EKKLESIA_SMOKE_RECYCLE_WATCH_MS=120000 \
bash scripts/smoke-deploy.sh
ci/package.sh
-35
View File
@@ -1,35 +0,0 @@
#!/usr/bin/env bash
# Builds the one canonical linux-x64-glibc Module Package pair that later jobs must consume.
set -Eeuo pipefail
root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
release="${1:-$root/build/module-package}"
source_revision="${GITHUB_SHA:-$(git -C "$root" rev-parse HEAD 2>/dev/null || true)}"
[[ "$source_revision" =~ ^[0-9a-f]{40}$ ]] || {
echo "package: no full source revision is available." >&2
exit 1
}
rm -rf -- "$release"
mkdir -p -- "$release"
pnpm --dir "$root" build
pnpm --dir "$root" exec ekklesia-pack-module --module "$root" --target linux-x64-glibc \
--out "$release" --license-file "$root/LICENSE" --source-revision "$source_revision"
mapfile -t archives < <(find "$release" -maxdepth 1 -type f -name 'signage-*-linux-x64-glibc.tar.gz' -print)
[[ "${#archives[@]}" -eq 1 ]] || {
echo "package: expected exactly one Module Package archive." >&2
exit 1
}
archive="${archives[0]}"
checksum="$archive.sha256"
[[ -f "$checksum" ]] || {
echo "package: missing $(basename "$checksum")." >&2
exit 1
}
(cd "$release" && sha256sum --check --strict "$(basename "$checksum")")
digest="$(sha256sum "$archive" | cut -d' ' -f1)"
if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
echo "sha256=$digest" >>"$GITHUB_OUTPUT"
fi
echo "package: canonical pair is $(basename "$archive") and $(basename "$checksum")."
ci/platform.env
-5
View File
@@ -1,5 +0,0 @@
# The companion Core harness Signage uses to install and run its real external package. The pull ref
# remains reachable after its branch is deleted; the full commit pin makes the checkout immutable.
EKKLESIA_PLATFORM_REPOSITORY=https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia.git
EKKLESIA_PLATFORM_REF=refs/pull/90/head
EKKLESIA_PLATFORM_COMMIT=40ef0ff802c124ae5a3a0b9aa51a1502a7b72644
ci/release-assets.py
-263
View File
@@ -1,263 +0,0 @@
#!/usr/bin/env python3
"""Validate and publish one tested Signage release bundle through the Gitea API."""
from __future__ import annotations
import hashlib
import json
import os
import re
import sys
import tarfile
import urllib.error
import urllib.parse
import urllib.request
import uuid
from pathlib import Path
ARCHIVE = re.compile(r"^signage-(\d+\.\d+\.\d+)-linux-x64-glibc\.tar\.gz$")
class Refused(Exception):
"""The release does not meet a condition that must fail closed."""
def sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
def package_metadata(archive: Path) -> dict:
try:
with tarfile.open(archive, "r:gz") as bundle:
member = next(
entry for entry in bundle.getmembers()
if entry.name == "signage/ekklesia.package.json" and entry.isfile()
)
extracted = bundle.extractfile(member)
if extracted is None:
raise KeyError(member.name)
return json.loads(extracted.read())
except (KeyError, StopIteration, tarfile.TarError, json.JSONDecodeError) as error:
raise Refused(f"cannot read signage/ekklesia.package.json from {archive.name}") from error
def package_pair(directory: Path, tag: str, revision: str) -> list[Path]:
archives = [path for path in directory.iterdir() if path.is_file() and ARCHIVE.fullmatch(path.name)]
if len(archives) != 1:
raise Refused(f"expected one Signage Module Package, found {len(archives)}")
package = archives[0]
match = ARCHIVE.fullmatch(package.name)
assert match is not None
version = match.group(1)
if tag != f"v{version}":
raise Refused(f"tag {tag} does not match package version {version}")
if not re.fullmatch(r"[0-9a-f]{40}", revision):
raise Refused("release revision is not a full Git object ID")
checksum = directory / f"{package.name}.sha256"
expected = [package, checksum]
missing = [path.name for path in expected if not path.is_file()]
if missing:
raise Refused(f"Module Package pair is incomplete; missing={missing}")
package_digest = sha256(package)
checksum_line = checksum.read_text(encoding="utf-8")
wanted_line = f"{package_digest} {package.name}\n"
if checksum_line != wanted_line:
raise Refused(f"{checksum.name} does not match {package.name}")
built_digest = os.environ.get("EXPECTED_PACKAGE_SHA256")
if built_digest is not None and built_digest != package_digest:
raise Refused("selected Module Package differs from the package job's bytes")
metadata = package_metadata(package)
if metadata.get("module") != {"id": "signage", "version": version}:
raise Refused("package metadata does not identify the expected Signage version")
if metadata.get("provenance", {}).get("revision") != revision:
raise Refused("package provenance revision does not match the tag commit")
return expected
def expected_paths(directory: Path, tag: str, revision: str) -> list[Path]:
package, checksum = package_pair(directory, tag, revision)
package_digest = sha256(package)
match = ARCHIVE.fullmatch(package.name)
assert match is not None
version = match.group(1)
source = directory / f"signage-{version}-linux-x64-glibc-corresponding-source.tar.gz"
source_checksum = directory / f"{source.name}.sha256"
redistribution = directory / f"signage-{version}-linux-x64-glibc.redistribution.json"
notice = directory / f"signage-{version}-linux-x64-glibc.source-notice.txt"
expected = [package, checksum, source, source_checksum, redistribution, notice]
missing = [path.name for path in expected if not path.is_file()]
extras = sorted(path.name for path in directory.iterdir() if path.is_file() and path not in expected)
if missing or extras:
raise Refused(f"release bundle differs from the six required files; missing={missing}, extra={extras}")
source_line = source_checksum.read_text(encoding="utf-8")
wanted_source_line = f"{sha256(source)} {source.name}\n"
if source_line != wanted_source_line:
raise Refused(f"{source_checksum.name} does not match {source.name}")
binding = json.loads(redistribution.read_text(encoding="utf-8"))
package_binding = binding.get("package", {})
if package_binding.get("file") != package.name or package_binding.get("sha256") != package_digest:
raise Refused("redistribution metadata does not bind the selected Module Package")
corresponding = binding.get("correspondingSource", {})
if corresponding.get("file") != source.name or corresponding.get("sha256") != sha256(source):
raise Refused("redistribution metadata does not bind the selected corresponding source")
return expected
class Gitea:
def __init__(self) -> None:
self.server = os.environ.get("GITHUB_SERVER_URL", "").rstrip("/")
self.repository = os.environ.get("GITHUB_REPOSITORY", "")
self.token = os.environ.get("GITHUB_TOKEN", "")
if not self.server or not self.repository or not self.token:
raise Refused("GITHUB_SERVER_URL, GITHUB_REPOSITORY, and GITHUB_TOKEN are required")
def request(self, method: str, path: str, body: bytes | None = None,
headers: dict[str, str] | None = None, *, authenticated: bool = True,
missing_ok: bool = False) -> bytes | None:
target = path if path.startswith("http") else f"{self.server}/api/v1/repos/{self.repository}{path}"
request_headers = dict(headers or {})
if authenticated:
request_headers["Authorization"] = f"token {self.token}"
request = urllib.request.Request(target, data=body, method=method, headers=request_headers)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return response.read()
except urllib.error.HTTPError as error:
if missing_ok and error.code == 404:
return None
detail = error.read()[:300].decode("utf-8", "replace")
raise Refused(f"{method} {path} answered {error.code}: {detail}") from error
def json(self, method: str, path: str, body: object | None = None,
*, missing_ok: bool = False) -> object:
encoded = json.dumps(body).encode() if body is not None else None
headers = {"Content-Type": "application/json"} if encoded is not None else None
data = self.request(method, path, encoded, headers, missing_ok=missing_ok)
return json.loads(data) if data is not None else None
def public_download(self, url: str) -> bytes:
return self.request("GET", url, authenticated=False)
def publish(directory: Path, tag: str, revision: str) -> None:
# This validates every local byte before the first API request, and therefore before creating or
# mutating a release. Corresponding-source policy verification happens in the workflow first.
files = expected_paths(directory, tag, revision)
gitea = Gitea()
quoted_tag = urllib.parse.quote(tag, safe="")
release = gitea.json("GET", f"/releases/tags/{quoted_tag}", missing_ok=True)
tagged = gitea.json("GET", f"/tags/{quoted_tag}", missing_ok=True)
if tagged is not None and (
not isinstance(tagged, dict) or tagged.get("commit", {}).get("sha") != revision
):
raise Refused(f"existing tag {tag} does not name {revision}")
if release is not None and tagged is None:
raise Refused(f"release {tag} exists without a readable tag")
if release is None:
release = gitea.json("POST", "/releases", {
"tag_name": tag,
# A full immutable commit, never a moving branch, is the release's tag target.
"target_commitish": revision,
"name": f"Ekklesia Signage {tag}",
"body": (
"Published by the manual Publish Signage Release workflow after package, "
"external integration, and corresponding-source verification."
),
# Existing Signage 0.x releases use Gitea's prerelease convention.
"draft": False,
"prerelease": True,
})
if not isinstance(release, dict):
raise Refused(f"Gitea did not return the created release {tag}")
tagged = gitea.json("GET", f"/tags/{quoted_tag}")
if not isinstance(tagged, dict) or tagged.get("commit", {}).get("sha") != revision:
raise Refused(f"created tag {tag} does not name {revision}")
elif not isinstance(release, dict):
raise Refused(f"cannot read release {tag}")
release_id = release.get("id")
if not isinstance(release_id, int):
raise Refused(f"release {tag} has no numeric id")
listed = gitea.json("GET", f"/releases/{release_id}/assets")
present = {asset["name"]: asset for asset in listed or []}
unexpected = sorted(set(present) - {path.name for path in files})
if unexpected:
raise Refused(f"release already has unexpected assets: {unexpected}")
# Preflight every published name before changing the release. This prevents a later conflict
# from leaving newly uploaded earlier files beside immutable, different bytes.
verified: dict[str, str] = {}
for path in files:
asset = present.get(path.name)
if asset is None:
continue
public_digest = hashlib.sha256(gitea.public_download(asset["browser_download_url"])).hexdigest()
expected_digest = sha256(path)
if public_digest != expected_digest:
raise Refused(f"public {path.name} has sha256 {public_digest}, expected {expected_digest}")
verified[path.name] = public_digest
for path in files:
digest = sha256(path)
asset = present.get(path.name)
if asset is None:
boundary = uuid.uuid4().hex
body = (
f"--{boundary}\r\n"
f'Content-Disposition: form-data; name="attachment"; filename="{path.name}"\r\n'
"Content-Type: application/octet-stream\r\n\r\n"
).encode() + path.read_bytes() + f"\r\n--{boundary}--\r\n".encode()
gitea.request(
"POST",
f"/releases/{release_id}/assets?name={urllib.parse.quote(path.name)}",
body,
{"Content-Type": f"multipart/form-data; boundary={boundary}"},
)
listed = gitea.json("GET", f"/releases/{release_id}/assets")
asset = next((item for item in listed or [] if item.get("name") == path.name), None)
if asset is None:
raise Refused(f"Gitea did not list {path.name} after upload")
public_digest = verified.get(path.name)
if public_digest is None:
public_digest = hashlib.sha256(gitea.public_download(asset["browser_download_url"])).hexdigest()
if public_digest != digest:
raise Refused(f"public {path.name} has sha256 {public_digest}, expected {digest}")
print(f"release-assets: public {path.name}, sha256 {digest}", flush=True)
def main(argv: list[str]) -> int:
try:
if len(argv) != 4 or argv[0] not in {"verify-package", "verify", "publish"}:
raise Refused(
"usage: release-assets.py (verify-package|verify|publish) DIRECTORY TAG REVISION"
)
command, directory, tag, revision = argv
selected = (package_pair(Path(directory), tag, revision)
if command == "verify-package"
else expected_paths(Path(directory), tag, revision))
if command in {"verify-package", "verify"}:
for path in selected:
print(path)
else:
publish(Path(directory), tag, revision)
return 0
except (OSError, json.JSONDecodeError, Refused) as error:
print(f"release-assets: REFUSED: {error}", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))
ci/test_release_assets.py
-253
View File
@@ -1,253 +0,0 @@
#!/usr/bin/env python3
"""Release selection and Gitea upload tests; no real server or credential is used."""
from __future__ import annotations
import contextlib
import hashlib
import http.server
import importlib.util
import io
import json
import os
import socketserver
import tarfile
import tempfile
import threading
import unittest
import urllib.parse
from pathlib import Path
from unittest import mock
HERE = Path(__file__).resolve().parent
SPEC = importlib.util.spec_from_file_location("release_assets", HERE / "release-assets.py")
assert SPEC is not None and SPEC.loader is not None
release_assets = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(release_assets)
VERSION = "1.2.3"
REVISION = "a" * 40
def digest(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def release_bundle(directory: Path) -> list[Path]:
package = directory / f"signage-{VERSION}-linux-x64-glibc.tar.gz"
metadata = json.dumps({
"module": {"id": "signage", "version": VERSION},
"provenance": {"revision": REVISION},
}).encode()
with tarfile.open(package, "w:gz") as archive:
member = tarfile.TarInfo("signage/ekklesia.package.json")
member.size = len(metadata)
archive.addfile(member, io.BytesIO(metadata))
checksum = directory / f"{package.name}.sha256"
checksum.write_text(f"{release_assets.sha256(package)} {package.name}\n", encoding="utf-8")
source = directory / f"signage-{VERSION}-linux-x64-glibc-corresponding-source.tar.gz"
source.write_bytes(b"corresponding source")
source_checksum = directory / f"{source.name}.sha256"
source_checksum.write_text(f"{release_assets.sha256(source)} {source.name}\n", encoding="utf-8")
redistribution = directory / f"signage-{VERSION}-linux-x64-glibc.redistribution.json"
redistribution.write_text(json.dumps({
"package": {"file": package.name, "sha256": release_assets.sha256(package)},
"correspondingSource": {"file": source.name, "sha256": release_assets.sha256(source)},
}), encoding="utf-8")
notice = directory / f"signage-{VERSION}-linux-x64-glibc.source-notice.txt"
notice.write_text("source notice\n", encoding="utf-8")
return [package, checksum, source, source_checksum, redistribution, notice]
class FakeGitea(http.server.BaseHTTPRequestHandler):
assets: dict[str, bytes] = {}
release_exists = True
tag_revision: str | None = REVISION
api_authorizations: list[str | None] = []
public_authorizations: list[str | None] = []
asset_posts = 0
release_posts = 0
release_request: dict[str, object] | None = None
def log_message(self, _format: str, *_args: object) -> None:
pass
def answer(self, status: int, body: object = None) -> None:
data = b"" if body is None else json.dumps(body).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def asset_list(self) -> list[dict[str, object]]:
server = self.server
assert isinstance(server, socketserver.TCPServer)
host, port = server.server_address
return [
{"id": index, "name": name, "browser_download_url": f"http://{host}:{port}/public/{name}"}
for index, name in enumerate(self.assets, 1)
]
def do_GET(self) -> None: # noqa: N802 - BaseHTTPRequestHandler's API
if self.path.startswith("/public/"):
self.public_authorizations.append(self.headers.get("Authorization"))
name = urllib.parse.unquote(self.path.removeprefix("/public/"))
data = self.assets[name]
self.send_response(200)
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
return
self.api_authorizations.append(self.headers.get("Authorization"))
if "/releases/tags/" in self.path:
if self.release_exists:
self.answer(200, {"id": 7, "tag_name": f"v{VERSION}"})
else:
self.answer(404, {"message": "not found"})
elif "/tags/" in self.path:
if self.tag_revision is not None:
self.answer(200, {"commit": {"sha": self.tag_revision}})
else:
self.answer(404, {"message": "not found"})
elif self.path.endswith("/releases/7/assets"):
self.answer(200, self.asset_list())
else:
self.answer(404, {"message": "not found"})
def do_POST(self) -> None: # noqa: N802 - BaseHTTPRequestHandler's API
self.api_authorizations.append(self.headers.get("Authorization"))
length = int(self.headers["Content-Length"])
body = self.rfile.read(length)
if self.path.endswith("/releases"):
request = json.loads(body)
self.__class__.release_posts += 1
self.__class__.release_request = request
self.__class__.release_exists = True
self.__class__.tag_revision = request["target_commitish"]
self.answer(201, {"id": 7, "tag_name": request["tag_name"]})
return
self.__class__.asset_posts += 1
name = urllib.parse.parse_qs(urllib.parse.urlsplit(self.path).query)["name"][0]
boundary = self.headers["Content-Type"].split("boundary=", 1)[1].encode()
payload = body.split(b"\r\n\r\n", 1)[1].rsplit(b"\r\n--" + boundary + b"--", 1)[0]
self.assets[name] = payload
self.answer(201, {"name": name})
@contextlib.contextmanager
def fake_gitea(initial: dict[str, bytes] | None = None, *, release_exists: bool = True,
tag_revision: str | None = REVISION):
FakeGitea.assets = dict(initial or {})
FakeGitea.release_exists = release_exists
FakeGitea.tag_revision = tag_revision
FakeGitea.api_authorizations = []
FakeGitea.public_authorizations = []
FakeGitea.asset_posts = 0
FakeGitea.release_posts = 0
FakeGitea.release_request = None
with socketserver.TCPServer(("127.0.0.1", 0), FakeGitea) as server:
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
host, port = server.server_address
old = {name: os.environ.get(name) for name in ("GITHUB_SERVER_URL", "GITHUB_REPOSITORY", "GITHUB_TOKEN")}
os.environ.update({
"GITHUB_SERVER_URL": f"http://{host}:{port}",
"GITHUB_REPOSITORY": "owner/repository",
"GITHUB_TOKEN": "test-token",
})
try:
yield
finally:
server.shutdown()
thread.join()
for name, value in old.items():
if value is None:
os.environ.pop(name, None)
else:
os.environ[name] = value
class ReleaseAssetsTest(unittest.TestCase):
def test_selects_only_the_complete_bound_bundle(self) -> None:
with tempfile.TemporaryDirectory() as temporary:
directory = Path(temporary)
expected = release_bundle(directory)
self.assertEqual(release_assets.expected_paths(directory, f"v{VERSION}", REVISION), expected)
(directory / "unexpected.txt").write_text("no", encoding="utf-8")
with self.assertRaisesRegex(release_assets.Refused, "six required files"):
release_assets.expected_paths(directory, f"v{VERSION}", REVISION)
def test_refuses_wrong_tag_revision_and_checksum(self) -> None:
with tempfile.TemporaryDirectory() as temporary:
directory = Path(temporary)
paths = release_bundle(directory)
with self.assertRaisesRegex(release_assets.Refused, "tag"):
release_assets.expected_paths(directory, "v9.9.9", REVISION)
with self.assertRaisesRegex(release_assets.Refused, "provenance"):
release_assets.expected_paths(directory, f"v{VERSION}", "b" * 40)
with mock.patch.dict(os.environ, {"EXPECTED_PACKAGE_SHA256": "0" * 64}):
with self.assertRaisesRegex(release_assets.Refused, "package job's bytes"):
release_assets.expected_paths(directory, f"v{VERSION}", REVISION)
paths[1].write_text(f"{'0' * 64} {paths[0].name}\n", encoding="utf-8")
with self.assertRaisesRegex(release_assets.Refused, "does not match"):
release_assets.expected_paths(directory, f"v{VERSION}", REVISION)
def test_creates_release_uploads_each_byte_and_reads_it_back_anonymously(self) -> None:
with tempfile.TemporaryDirectory() as temporary:
directory = Path(temporary)
expected = release_bundle(directory)
with fake_gitea(release_exists=False, tag_revision=None):
release_assets.publish(directory, f"v{VERSION}", REVISION)
self.assertEqual(FakeGitea.release_posts, 1)
self.assertEqual(FakeGitea.release_request, {
"tag_name": f"v{VERSION}",
"target_commitish": REVISION,
"name": f"Ekklesia Signage v{VERSION}",
"body": (
"Published by the manual Publish Signage Release workflow after package, "
"external integration, and corresponding-source verification."
),
"draft": False,
"prerelease": True,
})
self.assertEqual(FakeGitea.asset_posts, 6)
self.assertEqual(FakeGitea.assets, {path.name: path.read_bytes() for path in expected})
self.assertTrue(all(value == "token test-token" for value in FakeGitea.api_authorizations))
self.assertEqual(FakeGitea.public_authorizations, [None] * 6)
def test_existing_identical_assets_are_idempotent_but_conflicts_fail(self) -> None:
with tempfile.TemporaryDirectory() as temporary:
directory = Path(temporary)
expected = release_bundle(directory)
initial = {path.name: path.read_bytes() for path in expected}
with fake_gitea(initial):
release_assets.publish(directory, f"v{VERSION}", REVISION)
self.assertEqual(FakeGitea.release_posts, 0)
self.assertEqual(FakeGitea.asset_posts, 0)
conflicting = {expected[1].name: b"different published bytes"}
with fake_gitea(conflicting):
with self.assertRaisesRegex(release_assets.Refused, "public .* expected"):
release_assets.publish(directory, f"v{VERSION}", REVISION)
self.assertEqual(FakeGitea.release_posts, 0)
self.assertEqual(FakeGitea.asset_posts, 0)
def test_refuses_existing_tag_at_another_revision_before_mutation(self) -> None:
with tempfile.TemporaryDirectory() as temporary:
directory = Path(temporary)
release_bundle(directory)
with fake_gitea(release_exists=False, tag_revision="b" * 40):
with self.assertRaisesRegex(release_assets.Refused, "existing tag"):
release_assets.publish(directory, f"v{VERSION}", REVISION)
self.assertEqual(FakeGitea.release_posts, 0)
self.assertEqual(FakeGitea.asset_posts, 0)
if __name__ == "__main__":
unittest.main()
ekklesia.module.json
+4 -7
View File
@@ -1,15 +1,12 @@
{
"manifestVersion": 8,
"manifestVersion": 7,
"id": "signage",
"name": "Signage",
"description": "Visual programming, timelines, synchronized channels, and display delivery for church screens.",
"version": "0.1.3",
"version": "0.1.1",
"compatibility": {
"platform": "^0.2.0",
"moduleSdk": "^0.2.0"
},
"database": {
"abi": 1
"platform": "^0.1.0",
"moduleSdk": "^0.1.0"
},
"capabilities": [
{
package.json
+10 -18
View File
@@ -1,13 +1,8 @@
{
"name": "@ekklesia/signage",
"version": "0.1.3",
"version": "0.1.1",
"private": true,
"license": "AGPL-3.0-or-later",
"type": "module",
"packageManager": "[email protected]",
"engines": {
"node": ">=24.11.0 <25"
},
"description": "Ekklesia's visual programming, timeline, synchronization, and display-delivery module.",
"files": [
"dist",
@@ -28,27 +23,24 @@
"build": "tsc --project tsconfig.build.json && ekklesia-build-module-ui",
"lint": "biome lint .",
"migration:generate": "drizzle-kit generate --config=drizzle.config.ts",
"prepack": "pnpm run build",
"prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/signage",
"test": "vitest run",
"typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.ui.json && tsc --noEmit --project tsconfig.ui-test.json",
"validate": "node scripts/validate-module.mjs"
"typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.ui.json && tsc --noEmit --project tsconfig.ui-test.json"
},
"dependencies": {
"@ekklesia/design-tokens": "^0.2.3",
"@ekklesia/module-database": "^0.2.3",
"@ekklesia/module-sdk": "^0.2.3",
"@ekklesia/module-ui-sdk": "^0.2.3",
"@ekklesia/ui": "^0.2.3",
"@ekklesia/design-tokens": "workspace:*",
"@ekklesia/module-sdk": "workspace:*",
"@ekklesia/module-ui-sdk": "workspace:*",
"@ekklesia/ui": "workspace:*",
"drizzle-orm": "0.45.2",
"react": "19.2.8",
"react-dom": "19.2.8",
"sharp": "0.35.5"
"sharp": "0.35.4"
},
"devDependencies": {
"@biomejs/biome": "2.5.3",
"@ekklesia/module-pack": "0.2.3",
"@ekklesia/module-ui-build": "^0.2.3",
"@ekklesia/typescript-config": "^0.2.3",
"@ekklesia/module-ui-build": "workspace:*",
"@ekklesia/typescript-config": "workspace:*",
"@types/node": "24.13.3",
"@types/react": "19.2.18",
"@types/react-dom": "19.2.4",
pnpm-lock.yaml
Generated
-2556
View File
File diff suppressed because it is too large Load Diff
pnpm-workspace.yaml
-30
View File
@@ -1,30 +0,0 @@
# This repository's own pnpm settings. Signage is a single standalone package, not part of any other
# workspace; pnpm reads its settings from this file.
# esbuild, which the module UI build and the module packager run, has an install script. pnpm runs
# none it was not told to.
allowBuilds:
esbuild: true
# pnpm holds back any package younger than its minimum release age, and refuses a lockfile that names
# one. A new Ekklesia package train is that young on its release day. These exact versions, and only
# these, are the train this lockfile pins (published by Ekklesia's release workflow, ADR 0053), so
# they are exempt by version; a train bump replaces them, and everything else keeps the policy.
minimumReleaseAgeExclude:
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
- '@ekklesia/[email protected]'
# The narrowly scoped advisory remediation Signage had while it was built inside Ekklesia's workspace,
# kept now that it is not. GHSA-67mh-4wv8-2f99 (moderate): the vulnerable esbuild 0.18.20 is reached
# only through the deprecated @esbuild-kit/core-utils (drizzle-kit -> @esbuild-kit/esm-loader), whose
# pinned range predates the fix. Scoped to that one edge, exactly as Ekklesia's own workspace does,
# so drizzle-kit's direct esbuild and Vite's are not dragged to another version.
overrides:
"@esbuild-kit/core-utils>esbuild": "0.25.12"
scripts/validate-module.mjs
-145
View File
@@ -1,145 +0,0 @@
// Validates the built Signage package and its migrations the way the platform reads them, with only
// Ekklesia's published module-development packages: no Ekklesia checkout, no database.
//
// pnpm build && pnpm validate
//
// What it checks:
// - the manifest parses, and its id and version match package.json and the built runtime;
// - every declared entrypoint exists in the built package;
// - the built runtime declares the same Module Database ABI as the manifest (Core refuses a
// mismatch);
// - the built schema entrypoint's only export is plain ABI v1 metadata for this module's own,
// namespaced tables, and every foreign key targets one of them;
// - the installed module SDK satisfies the manifest's `compatibility.moduleSdk`;
// - the migration journal and policy parse, name the same migrations in the same order, and every
// migration's SQL is present.
//
// What it cannot check, because only Ekklesia itself can: compatibility with a particular platform
// installation, capability and module dependencies between installed modules, and a migration's
// checksum against a database's applied history. The module packager and the platform's package
// verifier re-check all of the above when Signage is built as a Module Package.
import { readFile, stat } from "node:fs/promises";
import { fileURLToPath, pathToFileURL } from "node:url";
import { defineModuleSchemaMetadata, moduleTablePrefix } from "@ekklesia/module-database";
import {
parseDrizzleMigrationJournal,
parseModuleManifest,
parseModuleMigrationPolicy,
} from "@ekklesia/module-sdk";
const root = fileURLToPath(new URL("..", import.meta.url));
const failures = [];
const passes = [];
function check(condition, description) {
(condition ? passes : failures).push(description);
}
async function json(relative) {
return JSON.parse(await readFile(new URL(relative, pathToFileURL(root)), "utf8"));
}
async function exists(relative) {
try {
return (await stat(new URL(relative, pathToFileURL(root)))).isFile();
} catch {
return false;
}
}
/** A caret range, `^X.Y.Z`, as the platform's manifests write them. Anything else is refused here
* rather than half understood. */
function satisfiesCaret(version, range) {
const wanted = /^\^(\d+)\.(\d+)\.(\d+)$/u.exec(range);
const actual = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version);
if (!wanted || !actual) {
return false;
}
const [w, a] = [wanted.slice(1).map(Number), actual.slice(1).map(Number)];
if (w[0] !== a[0] || (w[0] === 0 && w[1] !== a[1])) {
return false;
}
for (let index = 0; index < 3; index += 1) {
if (a[index] !== w[index]) {
return a[index] > w[index];
}
}
return true;
}
const packageJson = await json("package.json");
const manifest = parseModuleManifest(await json("ekklesia.module.json"));
check(true, "ekklesia.module.json is a valid manifest");
check(packageJson.version === manifest.version, "package.json and the manifest name one version");
check(packageJson.type === "module", "the package is ESM");
check(packageJson.ekklesia?.layer === "module", "the package carries the module layer marker");
const { server, schema, migrations, ui, display } = manifest.entrypoints;
for (const entrypoint of [server, schema, ui, display?.artifact].filter(Boolean)) {
check(await exists(entrypoint), `the built package has ${entrypoint}`);
}
const runtime = (await import(new URL(server, pathToFileURL(root)).href)).default;
check(runtime?.id === manifest.id, "the built runtime's id is the manifest's");
check(runtime?.version === manifest.version, "the built runtime's version is the manifest's");
check(
JSON.stringify(runtime?.database ?? null) === JSON.stringify(manifest.database ?? null),
"the built runtime declares the manifest's database ABI",
);
if (schema) {
const namespace = await import(new URL(schema, pathToFileURL(root)).href);
check(
Object.keys(namespace).join() === "default",
"the schema entrypoint exports nothing but its metadata",
);
const metadata = defineModuleSchemaMetadata(namespace.default);
check(
JSON.stringify(JSON.parse(JSON.stringify(metadata))) === JSON.stringify(metadata),
"the schema metadata is plain data",
);
check(metadata.moduleId === manifest.id, "the schema metadata is this module's");
const prefix = moduleTablePrefix(manifest.id);
const owned = new Set(metadata.tables.map((table) => table.name));
check(
metadata.tables.every((table) => table.name.startsWith(prefix)),
`every table is in the ${prefix} namespace`,
);
check(
metadata.tables.every((table) => table.foreignKeys.every((key) => owned.has(key.table))),
"every foreign key targets one of this module's own tables",
);
}
const sdkVersion = (await json("node_modules/@ekklesia/module-sdk/package.json")).version;
check(
satisfiesCaret(sdkVersion, manifest.compatibility.moduleSdk),
`the installed module SDK ${sdkVersion} satisfies compatibility.moduleSdk ${manifest.compatibility.moduleSdk}`,
);
if (migrations) {
const directory = migrations.endsWith("/") ? migrations : `${migrations}/`;
const journal = parseDrizzleMigrationJournal(await json(`${directory}meta/_journal.json`));
const policy = parseModuleMigrationPolicy(await json(`${directory}meta/_ekklesia.json`));
check(policy.moduleId === manifest.id, "the migration policy is this module's");
check(
journal.entries.map((entry) => entry.tag).join() ===
policy.entries.map((entry) => entry.tag).join(),
"the migration journal and policy name the same migrations in the same order",
);
for (const entry of journal.entries) {
check(await exists(`${directory}${entry.tag}.sql`), `${entry.tag}.sql is present`);
}
}
for (const description of passes) {
console.log(`ok ${description}`);
}
for (const description of failures) {
console.log(`FAIL ${description}`);
}
if (failures.length > 0) {
console.error(`validate: ${failures.length} check(s) failed.`);
process.exit(1);
}
console.log(`validate: ${manifest.id}@${manifest.version} passed ${passes.length} checks.`);
src/browser/backoff.ts
-21
View File
@@ -1,21 +0,0 @@
/**
* How long a display waits before trying a failed request again.
*
* Exponential from one second to a one-minute ceiling, so a screen whose server is restarting is
* back within seconds, and one whose server is down for an evening asks once a minute rather than
* hammering it. The wait is jittered between half and all of that step, so a building's worth of
* screens that lost the server at the same moment do not all come back at the same moment.
*
* There is no attempt limit. A television on a wall has nobody to press Retry, so giving up is the
* one thing it must never do.
*/
export const DISPLAY_RETRY_BASE_MS = 1_000;
export const DISPLAY_RETRY_MAX_MS = 60_000;
export function displayRetryDelayMs(attempt: number, random: () => number = Math.random): number {
const step = Math.min(
DISPLAY_RETRY_MAX_MS,
DISPLAY_RETRY_BASE_MS * 2 ** Math.min(Math.max(0, attempt), 16),
);
return Math.round(step / 2 + (step / 2) * Math.min(1, Math.max(0, random())));
}
src/browser/storage.ts
+3 -49
View File
@@ -36,9 +36,6 @@ export interface SignageMediaCache {
* can never leave a screen with less than it had. */
prune(keep: readonly string[]): Promise<void>;
count(): Promise<number>;
/** Gives back every local URL this cache handed out. Called when a display stops; a URL handed
* out before this is no longer valid afterwards. */
release(): void;
}
/** The stable key a native image's bytes are cached under. Deliberately built from identity, never
@@ -89,9 +86,6 @@ export function createMemoryMediaCache(): SignageMediaCache {
}
return Promise.resolve();
},
release(): void {
// Holds plain URLs, nothing the browser has to be given back.
},
store(key: string, url: string): Promise<string | undefined> {
stored.set(key, url);
return Promise.resolve(url);
@@ -185,45 +179,14 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
return `${origin}/${key}`;
}
/**
* The one object URL each cached slide is rendered from, by cache entry.
*
* An object URL pins its blob in the browser until it is revoked. Every state refresh looks every
* cached slide up again, so minting a URL per lookup leaked a blob per slide per refresh, and
* within minutes the browser refused the display's own requests for want of resources. So each
* entry gets exactly one URL, revoked when the entry is pruned or replaced, and all of them when
* the display stops.
*/
const objectUrls = new Map<string, string>();
function forget(request: string): void {
const url = objectUrls.get(request);
if (url !== undefined) {
objectUrls.delete(request);
URL.revokeObjectURL(url);
}
}
async function localUrl(cache: Cache, request: string): Promise<string | undefined> {
const existing = objectUrls.get(request);
if (existing !== undefined) {
return existing;
}
const response = await cache.match(request);
async function localUrl(cache: Cache, url: string): Promise<string | undefined> {
const response = await cache.match(url);
if (!response) {
return undefined;
}
try {
const blob = await response.blob();
// Two lookups of one slide can be in flight at once; the first to finish wins, and the other
// gives its URL straight back rather than leaving it pinned.
const raced = objectUrls.get(request);
if (raced !== undefined) {
return raced;
}
const url = URL.createObjectURL(blob);
objectUrls.set(request, url);
return url;
return URL.createObjectURL(blob);
} catch {
return undefined;
}
@@ -257,7 +220,6 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
for (const request of await cache.keys()) {
if (!retained.has(request.url)) {
await cache.delete(request);
forget(request.url);
}
}
} catch {
@@ -265,12 +227,6 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
}
},
release(): void {
for (const request of [...objectUrls.keys()]) {
forget(request);
}
},
async store(key: string, url: string): Promise<string | undefined> {
const cache = await open();
if (!cache) {
@@ -286,8 +242,6 @@ export function createBrowserMediaCache(scope: typeof globalThis = globalThis):
// Stored under the *stable* key, so the next refresh's freshly signed URL finds these
// bytes instead of downloading them again.
await cache.put(cacheRequest(key), response.clone());
// New bytes under this key: the URL for the old ones is given back before one is made.
forget(cacheRequest(key));
return localUrl(cache, cacheRequest(key));
} catch {
return undefined;
src/display/controller.ts
+40 -126
View File
@@ -1,5 +1,4 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { displayRetryDelayMs } from "../browser/backoff.js";
import {
type OfflineSnapshot,
resolveOffline,
@@ -123,13 +122,6 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
let snapshot: OfflineSnapshot | undefined;
let offlineActive = false;
let offlineHandle: unknown;
/** Retries, each on its own backoff. A display has nobody to press Retry, so none of them give up;
* each resets once its request works again. */
let sessionHandle: unknown;
let sessionAttempt = 0;
let refreshAttempt = 0;
let realtimeHandle: unknown;
let realtimeAttempt = 0;
/** Selections this display has tried and failed to render. A broken item is skipped rather than
* retried in a tight loop, which is what keeps one bad slide from becoming a flicker. */
const unusable = new Set<string>();
@@ -505,119 +497,17 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
`channels/${session.channelId}/display-state`,
);
if (!response.ok) {
await refreshFailed();
online = false;
await runOffline();
return;
}
const state = (await response.json()) as DisplayChannelStateView;
refreshAttempt = 0;
await apply(state);
await apply((await response.json()) as DisplayChannelStateView);
} catch {
await refreshFailed();
}
}
/**
* The server is unreachable, or answered with an error. The frame stays and local continuation
* takes over — nothing about a network failure belongs on a lobby wall — and the refresh is tried
* again on its own, because a realtime message that would otherwise prompt it may never come.
*/
async function refreshFailed(): Promise<void> {
online = false;
await runOffline();
if (stopped) {
return;
}
if (refreshHandle !== undefined) {
clearTimer(refreshHandle);
}
refreshHandle = setTimer(() => {
refreshHandle = undefined;
void refresh();
}, displayRetryDelayMs(refreshAttempt));
refreshAttempt += 1;
}
/**
* Registers this display, and keeps trying until it can.
*
* Until it has registered, a display continues from its own persisted state, honestly marked as
* offline. The first registration that works brings it live — realtime, heartbeats, and fresh
* state — exactly as if it had worked the first time.
*/
async function register(): Promise<void> {
if (stopped || session) {
return;
}
let registered: DisplaySessionView | undefined;
try {
const response = await options.context.api.request("viewers/session", {
body: JSON.stringify({ viewerKey: await viewerKey() }),
headers: { "content-type": "application/json" },
method: "POST",
});
if (response.ok) {
// Read, not cast: a registration the display cannot understand is no registration, and is
// tried again like any other failure.
const parsed = parseViewerSessionResponse(await response.json());
registered = parsed.ok ? parsed.value : undefined;
}
} catch {
registered = undefined;
}
if (stopped) {
return;
}
if (!registered) {
// The server is unreachable. The frame stays and local continuation takes over; nothing about
// a network failure belongs on a lobby wall.
online = false;
report();
sessionHandle = setTimer(() => {
sessionHandle = undefined;
void register();
}, displayRetryDelayMs(sessionAttempt));
sessionAttempt += 1;
return;
await runOffline();
}
sessionAttempt = 0;
session = registered;
online = true;
subscribe();
heartbeatHandle = setInterval(
() => void heartbeat(),
registered.heartbeatIntervalMs,
) as unknown;
await refresh();
void heartbeat();
report();
}
/**
* Subscribes to the display's realtime channel, and again whenever the host reports that a
* subscription has ended for good. The host retries ordinary disconnects itself; a stream that
* is refused outright ends, and until this resubscribes the display would only learn of changes
* at its next slot deadline.
*/
function subscribe(): void {
if (stopped || !session) {
return;
}
subscription?.close();
subscription = options.context.realtime.subscribe("display-state", {
onSnapshot: (state) => onRealtime(state),
onStatus: (status) => {
online = status === "connected";
if (status === "connected") {
realtimeAttempt = 0;
} else if (status === "closed" && !stopped && realtimeHandle === undefined) {
realtimeHandle = setTimer(() => {
realtimeHandle = undefined;
subscribe();
}, displayRetryDelayMs(realtimeAttempt));
realtimeAttempt += 1;
}
report();
},
onUpdate: (state) => onRealtime(state),
});
}
async function heartbeat(): Promise<void> {
@@ -688,7 +578,40 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
}
if (telemetry) {
await register();
try {
const response = await options.context.api.request("viewers/session", {
body: JSON.stringify({ viewerKey: await viewerKey() }),
headers: { "content-type": "application/json" },
method: "POST",
});
if (response.ok) {
// Read, not cast: a registration the display cannot understand is no registration.
const parsed = parseViewerSessionResponse(await response.json());
if (parsed.ok) {
session = parsed.value;
online = true;
}
}
} catch {
online = false;
}
}
if (session) {
subscription = options.context.realtime.subscribe("display-state", {
onSnapshot: (state) => onRealtime(state),
onStatus: (status) => {
online = status === "connected";
report();
},
onUpdate: (state) => onRealtime(state),
});
heartbeatHandle = setInterval(
() => void heartbeat(),
session.heartbeatIntervalMs,
) as unknown;
await refresh();
void heartbeat();
}
report();
},
@@ -705,18 +628,9 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
clearTimer(refreshHandle);
refreshHandle = undefined;
}
for (const handle of [sessionHandle, realtimeHandle]) {
if (handle !== undefined) {
clearTimer(handle);
}
}
sessionHandle = undefined;
realtimeHandle = undefined;
exitOffline();
await stage?.destroy();
stage = undefined;
// After the stage is gone, so nothing on screen still points at a released URL.
media.release();
},
};
src/display/index.tsx
+1 -1
View File
@@ -59,7 +59,7 @@ function SignageDisplay({ context }: { readonly context: ModuleUiHostContext }):
*/
export default defineModuleUi({
id: "signage",
version: "0.1.3",
version: "0.1.1",
styles: displayStyles,
mount(container, context) {
const root = createRoot(container);
src/schema/index.ts
+25 -12
View File
@@ -1,4 +1,4 @@
import { moduleDrizzleSchemaMetadata } from "@ekklesia/module-database/drizzle";
import { defineModuleSchema } from "@ekklesia/module-sdk";
import {
channelGroups,
channels,
@@ -13,16 +13,7 @@ import {
viewers,
} from "./tables.js";
/**
* Signage's compiled schema entrypoint: the plain Module Database ABI v1 metadata Core validates
* table ownership from (platform ADR 0050) — each table's physical name and the tables its foreign
* keys target, as strings and arrays.
*
* Derived on this side from the same Drizzle tables `tables.ts` declares, so it cannot drift from
* them, and deliberately the **only** export: Core never receives a Drizzle object from Signage.
* Side-effect free by contract — importing this connects to nothing and reads nothing.
*/
export default moduleDrizzleSchemaMetadata("signage", {
export {
channelGroups,
channels,
imageAssets,
@@ -31,7 +22,29 @@ export default moduleDrizzleSchemaMetadata("signage", {
providerSources,
selections,
selectionVariants,
timelines,
timelineSlots,
timelines,
viewers,
} from "./tables.js";
/**
* Signage's compiled schema entrypoint: the same table objects `tables.ts` declares, wrapped with the
* ownership marker Core validates during discovery. Side-effect free by contract — importing this
* connects to nothing and reads nothing.
*/
export default defineModuleSchema({
moduleId: "signage",
tables: {
channelGroups,
channels,
imageAssets,
imageRenditions,
playbackStates,
providerSources,
selections,
selectionVariants,
timelines,
timelineSlots,
viewers,
},
});
src/schema/tables.ts
+3 -4
View File
@@ -17,10 +17,9 @@ import {
* Signage's own PostgreSQL tables.
*
* Kept to **pure Drizzle declarations** so the stable Drizzle Kit generator can load this file
* without executing any Ekklesia package; `./index.ts` derives the plain schema metadata Core
* validates from these same objects, and only Signage's own store code ever uses them as Drizzle
* tables. The required `signage_` namespace is applied once here, and Core validates it
* independently of this helper.
* without executing the ESM Module SDK wrapper; `./index.ts` wraps these same objects with the
* ownership marker Core validates. The required `signage_` namespace is applied once here, and Core
* validates it independently of this helper.
*
* Two rules hold everywhere below, and both are architecture rather than style:
*
src/server/images/processing.ts
+4 -5
View File
@@ -177,11 +177,10 @@ export async function processSignageImage(bytes: Uint8Array): Promise<SignagePro
height: metadata.height as number,
width: metadata.width as number,
};
// Keep peak native CPU and memory bounded inside the shared API process. Upload concurrency is
// already bounded at the module UI; running both renditions for every upload in parallel would
// multiply that concurrency again and can starve the database and storage clients on a small host.
const display = await renderRendition(bytes, SIGNAGE_IMAGE_DISPLAY_RENDITION);
const thumbnail = await renderRendition(bytes, SIGNAGE_IMAGE_THUMBNAIL_RENDITION);
const [display, thumbnail] = await Promise.all([
renderRendition(bytes, SIGNAGE_IMAGE_DISPLAY_RENDITION),
renderRendition(bytes, SIGNAGE_IMAGE_THUMBNAIL_RENDITION),
]);
return {
byteSize: bytes.byteLength,
src/server/images/service.ts
+3 -18
View File
@@ -1,9 +1,8 @@
import { randomUUID } from "node:crypto";
import {
MODULE_STORAGE_ERROR_CODES,
type ModuleStorage,
type ModuleStorageBucket,
type ModuleStorageErrorCode,
ModuleStorageError,
} from "@ekklesia/module-sdk";
import { SignageError } from "../errors.js";
import { type SignageStore, SignageStoreConflict, type StoredImage } from "../store/types.js";
@@ -18,20 +17,6 @@ export function nativeImageBucket(storage: ModuleStorage): ModuleStorageBucket {
return storage.bucket(SIGNAGE_IMAGE_BUCKET);
}
/** Host errors cross the installed-package boundary from a different copy of the SDK, so class
* identity is not part of the contract (ADR 0049). Recognize only the SDK's closed, sanitized
* storage-error shape; provider messages and causes remain inaccessible. */
function storageErrorCode(error: unknown): ModuleStorageErrorCode | undefined {
if (!(error instanceof Error) || error.name !== "ModuleStorageError") {
return undefined;
}
const code = (error as { readonly code?: unknown }).code;
return typeof code === "string" &&
(MODULE_STORAGE_ERROR_CODES as readonly string[]).includes(code)
? (code as ModuleStorageErrorCode)
: undefined;
}
/**
* Object keys are scoped to the asset they belong to.
*
@@ -56,7 +41,7 @@ export function renditionObjectKey(assetId: string, kind: string): string {
* not a caller's business.
*/
function storageFailure(error: unknown): SignageError {
if (storageErrorCode(error) === "STORAGE_OBJECT_NOT_FOUND") {
if (error instanceof ModuleStorageError && error.code === "STORAGE_OBJECT_NOT_FOUND") {
return new SignageError("SIGNAGE_NOT_FOUND");
}
return new SignageError("SIGNAGE_STORAGE_UNAVAILABLE");
@@ -165,7 +150,7 @@ export async function ingestNativeImage(
if (error instanceof SignageError) {
throw error;
}
if (storageErrorCode(error) !== undefined) {
if (error instanceof ModuleStorageError) {
throw storageFailure(error);
}
throw new SignageError("SIGNAGE_OPERATION_FAILED");
src/server/runtime.ts
+3 -6
View File
@@ -89,7 +89,7 @@ export function createSignageModuleRuntime(
function requireStore(): ReturnType<typeof createSignageStore> {
if (!store) {
throw new Error("Signage's store is only available after start.");
throw new Error("Signage's database facade is only available after start.");
}
return store;
}
@@ -126,11 +126,8 @@ export function createSignageModuleRuntime(
}
const definition = defineModuleRuntime({
// Matches `database.abi` in the manifest: `context.services.database` is this module's Module
// Database ABI v1 executor, which `createSignageStore` binds Signage's own Drizzle adapter to.
database: { abi: 1 },
id: "signage",
version: "0.1.3",
version: "0.1.1",
register({ capabilities, config, http, realtime }) {
const settings = readSignageSettings(config);
@@ -192,7 +189,7 @@ export function createSignageModuleRuntime(
// server enforces — a UI believing a stale limit would offer an upload the server refuses.
return Response.json({
crossfadeMs: current.crossfadeMs,
moduleVersion: "0.1.3",
moduleVersion: "0.1.1",
nativeImageDurationMs: current.nativeImageDurationMs,
nativePresentation: current.nativePresentation,
rendererInputVersion: SIGNAGE_SLIDE_RENDERER_INPUT_VERSION,
src/server/store/drizzle-playback.ts
+2 -2
View File
@@ -1,5 +1,5 @@
import { randomUUID } from "node:crypto";
import type { ModuleDrizzleDatabase } from "@ekklesia/module-database/drizzle";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { and, asc, desc, eq, inArray, lt, sql } from "drizzle-orm";
import {
channelGroups,
@@ -94,7 +94,7 @@ function toSelection(
};
}
export function createPlaybackStore(database: ModuleDrizzleDatabase): SignagePlaybackStore {
export function createPlaybackStore(database: ModuleDatabase): SignagePlaybackStore {
async function variantsFor(
selectionIds: readonly string[],
): Promise<Map<string, StoredSelectionVariant[]>> {
src/server/store/drizzle-timelines.ts
+6 -12
View File
@@ -1,7 +1,4 @@
import type {
ModuleDrizzleDatabase,
ModuleDrizzleTransaction,
} from "@ekklesia/module-database/drizzle";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { asc, eq, or, sql } from "drizzle-orm";
import { playbackStates, providerSources, timelineSlots, timelines } from "../../schema/tables.js";
import {
@@ -111,7 +108,7 @@ function slotValues(slot: NewStoredSlot, position: number) {
};
}
export function createTimelineStore(database: ModuleDrizzleDatabase): SignageTimelineStore {
export function createTimelineStore(database: ModuleDatabase): SignageTimelineStore {
/**
* Rewrites `position` for one timeline from an explicit order.
*
@@ -121,7 +118,7 @@ export function createTimelineStore(database: ModuleDrizzleDatabase): SignageTim
* remaining inside the database's non-negative constraint.
*/
async function renumber(
transaction: ModuleDrizzleTransaction,
transaction: ModuleDatabase,
timelineId: string,
orderedSlotIds: readonly string[],
): Promise<void> {
@@ -141,10 +138,7 @@ export function createTimelineStore(database: ModuleDrizzleDatabase): SignageTim
await bumpRevision(transaction, timelineId);
}
async function bumpRevision(
transaction: ModuleDrizzleTransaction,
timelineId: string,
): Promise<void> {
async function bumpRevision(transaction: ModuleDatabase, timelineId: string): Promise<void> {
await transaction
.update(timelines)
.set({ revision: sql`${timelines.revision} + 1`, updatedAt: new Date() })
@@ -152,7 +146,7 @@ export function createTimelineStore(database: ModuleDrizzleDatabase): SignageTim
}
async function orderedSlotIdsFor(
transaction: ModuleDrizzleTransaction,
transaction: ModuleDatabase,
timelineId: string,
): Promise<string[]> {
const rows = await transaction
@@ -164,7 +158,7 @@ export function createTimelineStore(database: ModuleDrizzleDatabase): SignageTim
}
async function timelineIdForSlot(
transaction: ModuleDrizzleTransaction,
transaction: ModuleDatabase,
slotId: string,
): Promise<string | undefined> {
const rows = await transaction
src/server/store/drizzle-viewers.ts
+2 -2
View File
@@ -1,4 +1,4 @@
import type { ModuleDrizzleDatabase } from "@ekklesia/module-database/drizzle";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { asc, eq } from "drizzle-orm";
import { viewers } from "../../schema/tables.js";
import type { NewStoredViewer, SignageViewerStore, StoredViewer, ViewerChanges } from "./types.js";
@@ -29,7 +29,7 @@ function toViewer(row: typeof viewers.$inferSelect): StoredViewer {
};
}
export function createViewerStore(database: ModuleDrizzleDatabase): SignageViewerStore {
export function createViewerStore(database: ModuleDatabase): SignageViewerStore {
return {
async deleteViewer(viewerId: string): Promise<void> {
await database.delete(viewers).where(eq(viewers.id, viewerId));
src/server/store/drizzle.ts
+11 -17
View File
@@ -1,6 +1,5 @@
import { randomUUID } from "node:crypto";
import { findEkklesiaDatabaseError, type ModuleDatabaseExecutor } from "@ekklesia/module-database";
import { type ModuleDrizzleDatabase, moduleDrizzle } from "@ekklesia/module-database/drizzle";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { and, desc, eq, inArray } from "drizzle-orm";
import {
imageAssets,
@@ -23,16 +22,14 @@ import {
} from "./types.js";
/**
* The production implementation of Signage's data port, over the platform's Module Database ABI v1
* executor (platform ADR 0050) through the module-side Drizzle adapter.
* The production implementation of Signage's data port, over the platform's `ModuleDatabase`.
*
* This file is deliberately dull: it maps rows and nothing else. Every decision — what to write,
* when a revision changes, what a no-op is — lives in the services above it, so that behaviour can
* be proven without PostgreSQL and this mapping can be proven against a live one.
*
* The executor is the only way Signage reaches PostgreSQL. Drizzle compiles every query here, on
* Signage's side; Core receives SQL text and bound values and nothing else. Nothing here constructs a
* client, reads a connection string, or touches another module's table.
* The facade is the only way Signage reaches PostgreSQL. Nothing here constructs a client, reads a
* connection string, or touches another module's table.
*/
const assetColumns = {
@@ -69,11 +66,12 @@ const renditionColumns = {
width: imageRenditions.width,
};
/** PostgreSQL reports a uniqueness violation as SQLSTATE `23505`. Drizzle wraps whatever the
* executor throws, so the stable Ekklesia database error is found through that wrapping; its SQLSTATE
* is all that is read, and no driver error shape is ever relied on. */
/** PostgreSQL reports a uniqueness violation as SQLSTATE `23505`. The code is all that is read; the
* driver's message, detail, and constraint text are never surfaced. */
function isUniqueViolation(error: unknown): boolean {
return findEkklesiaDatabaseError(error)?.sqlState === "23505";
return (
typeof error === "object" && error !== null && (error as { code?: unknown }).code === "23505"
);
}
function toRendition(row: {
@@ -118,7 +116,7 @@ function toImage(row: AssetRow, renditions: readonly StoredImageRendition[]): St
};
}
export function createImageStore(database: ModuleDrizzleDatabase): SignageImageStore {
export function createImageStore(database: ModuleDatabase): SignageImageStore {
async function renditionsFor(
assetIds: readonly string[],
): Promise<Map<string, StoredImageRendition[]>> {
@@ -260,12 +258,8 @@ export function createImageStore(database: ModuleDrizzleDatabase): SignageImageS
*
* Composed rather than written as one object because the two halves share nothing but the database
* handle, and keeping them separate is what lets each be read on its own.
*
* Takes the ABI executor the platform hands a route handler or lifecycle hook, and binds Signage's
* own Drizzle adapter to it here, once, so every caller reaches its tables the same way.
*/
export function createSignageStore(executor: ModuleDatabaseExecutor): SignageStore {
const database = moduleDrizzle(executor);
export function createSignageStore(database: ModuleDatabase): SignageStore {
return {
...createImageStore(database),
...createTimelineStore(database),
src/server/store/types.ts
+1 -1
View File
@@ -3,7 +3,7 @@
*
* Every piece of Signage's behaviour — ingest, timeline editing, provider resolution, authoritative
* playback, viewer health — is written against this interface rather than against Drizzle directly.
* There are two implementations: the production one over the platform's database ABI executor
* There are two implementations: the production one over the platform's `ModuleDatabase`
* (`./drizzle.ts`), and an in-memory one used by tests.
*
* This is the same discipline Core's own migration runner follows, and it exists for the same
src/ui/index.tsx
+1 -1
View File
@@ -15,7 +15,7 @@ import ownStyles from "./styles.css";
*/
export default defineModuleUi({
id: "signage",
version: "0.1.3",
version: "0.1.1",
styles: `${EKKLESIA_UI_STYLESHEET}\n${ownStyles}`,
mount(container, context) {
const root = createRoot(container);
tests/acceptance.test.ts
+1 -3
View File
@@ -263,9 +263,7 @@ describe("what this release deliberately does not contain", () => {
]) {
expect(names).not.toContain(forbidden);
}
// The database is reached only through the platform's ABI executor, with Signage's own Drizzle
// adapter compiling the queries; there is no client of Signage's own.
// The database is reached only through the platform's facade; there is no client of Signage's own.
expect(names).toContain("drizzle-orm");
expect(names).toContain("@ekklesia/module-database");
});
});
tests/browser/backoff.test.ts
-34
View File
@@ -1,34 +0,0 @@
import { describe, expect, it } from "vitest";
import {
DISPLAY_RETRY_BASE_MS,
DISPLAY_RETRY_MAX_MS,
displayRetryDelayMs,
} from "../../src/browser/backoff.js";
describe("display retry backoff", () => {
it("doubles from one second and stops at one minute", () => {
const longest = (attempt: number) => displayRetryDelayMs(attempt, () => 1);
expect([0, 1, 2, 3, 4, 5, 6, 7, 50].map(longest)).toEqual([
1_000, 2_000, 4_000, 8_000, 16_000, 32_000, 60_000, 60_000, 60_000,
]);
});
it("jitters between half and all of each step, and never waits zero", () => {
for (const attempt of [0, 3, 6, 40]) {
const step = Math.min(DISPLAY_RETRY_MAX_MS, DISPLAY_RETRY_BASE_MS * 2 ** attempt);
expect(displayRetryDelayMs(attempt, () => 0)).toBe(step / 2);
expect(displayRetryDelayMs(attempt, () => 1)).toBe(step);
for (let index = 0; index < 50; index += 1) {
const delay = displayRetryDelayMs(attempt);
expect(delay).toBeGreaterThanOrEqual(step / 2);
expect(delay).toBeLessThanOrEqual(step);
}
}
});
it("treats a nonsensical attempt or random value as the nearest sensible one", () => {
expect(displayRetryDelayMs(-3, () => 1)).toBe(1_000);
expect(displayRetryDelayMs(2, () => 7)).toBe(4_000);
expect(displayRetryDelayMs(2, () => -1)).toBe(2_000);
});
});
tests/browser/display-recovery.test.ts
-307
View File
@@ -1,307 +0,0 @@
// @vitest-environment happy-dom
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { beforeEach, describe, expect, it } from "vitest";
import {
createMemoryMediaCache,
createMemoryStore,
type SignageLocalStore,
} from "../../src/browser/storage.js";
import {
createDisplayController,
type DisplayChannelStateView,
} from "../../src/display/controller.js";
import { createFakeHost, type FakeHost, jsonResponse } from "./support/fake-host.js";
/**
* A display never reaches a dead end.
*
* Every network path a display depends on — registering, fetching state, realtime — can fail once,
* as a kiosk that boots before its network settles or an API that restarts will make it. Each must
* be tried again, with backoff, until it works, and the display must then be exactly as live as if
* nothing had happened. None of it may need a person to reload a television.
*
* Time is virtual: every timer the controller schedules goes through the queue below.
*/
const SESSION = {
channelId: "chan-1",
channelKey: "default",
groupId: "group-1",
heartbeatIntervalMs: 12_000,
viewerId: "11111111-1111-4111-8111-111111111111",
viewerName: "Foyer",
};
function selection(id: string) {
return {
availableUntilMs: null,
deadlineAtMs: 5000,
durationMs: 5000,
id,
itemId: `image-${id}`,
itemRevision: "rev-1",
media: {
display: {
expiresAtMs: 900_000,
height: 1080,
url: `https://cdn.invalid/${id}`,
width: 1920,
},
thumbnail: {
expiresAtMs: 900_000,
height: 270,
url: `https://cdn.invalid/${id}-t`,
width: 480,
},
},
payload: { kind: "native-image" },
presentation: null,
providerId: "signage.native-images",
renderer: { kind: "native-image" as const },
revision: 1,
scene: {
backgroundColor: "#000000",
backgroundImage: false,
backgroundMode: "none" as const,
blurPixels: 0,
darkenOpacity: 0,
fit: "fill" as const,
shadow: false,
},
slotId: "slot-1",
stale: false,
startedAtMs: 0,
withdrawn: false,
};
}
function channelState(revision = 3): DisplayChannelStateView {
const current = selection("sel-1");
return {
channel: { groupId: "group-1", id: "chan-1", key: "default" },
crossfadeMs: 0,
current,
playback: {
activeTimelineId: "timeline-1",
blackout: false,
currentSelectionId: current.id,
currentSlotId: current.slotId,
deadlineAtMs: 5000,
pendingTimelineId: null,
remainingMs: 5000,
revision,
selectionRevision: 1,
startedAtMs: 0,
transport: "playing",
},
selections: [current],
serverNowMs: 0,
staticHold: null,
timeline: null,
};
}
/** Server behaviour that a test can change mid-run. */
interface Server {
sessionFailures: number;
stateFailing: boolean;
sessionRequests: number;
stateRequests: number;
}
describe("a display recovers from every failed request without a reload", () => {
let clock: number;
let timers: Map<number, { at: number; run: () => void }>;
let nextTimer: number;
let root: HTMLElement;
let local: SignageLocalStore;
let server: Server;
let host: FakeHost;
let subscriptions: { onStatus?: (status: string) => void }[];
beforeEach(() => {
clock = 0;
timers = new Map();
nextTimer = 1;
root = document.createElement("div");
document.body.append(root);
local = createMemoryStore();
server = { sessionFailures: 0, sessionRequests: 0, stateFailing: false, stateRequests: 0 };
subscriptions = [];
host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{
method: "POST",
path: "viewers/session",
respond: () => {
server.sessionRequests += 1;
if (server.sessionFailures > 0) {
server.sessionFailures -= 1;
throw new TypeError("Failed to fetch");
}
return jsonResponse(SESSION);
},
},
{
method: "GET",
path: "channels/chan-1/display-state",
respond: () => {
server.stateRequests += 1;
if (server.stateFailing) {
throw new TypeError("Failed to fetch");
}
return jsonResponse(channelState());
},
},
{ method: "POST", path: /^viewers\/.*\/heartbeat$/u, respond: () => jsonResponse({}) },
],
});
Object.assign(host.context, {
realtime: {
subscribe: (_channel: string, handlers: { onStatus?: (status: string) => void }) => {
subscriptions.push(handlers);
return { close: () => undefined };
},
} satisfies Pick<ModuleUiHostContext["realtime"], "subscribe"> as never,
});
});
async function settle(): Promise<void> {
for (let index = 0; index < 20; index += 1) {
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
/** Moves virtual time forward, firing every timer that falls due, in order. */
async function advance(ms: number): Promise<void> {
const end = clock + ms;
for (;;) {
const due = [...timers]
.filter(([, timer]) => timer.at <= end)
.sort((left, right) => left[1].at - right[1].at)[0];
if (!due) {
break;
}
timers.delete(due[0]);
clock = due[1].at;
due[1].run();
await settle();
}
clock = end;
}
function build() {
return createDisplayController({
clearTimer: (handle) => timers.delete(handle as number),
context: host.context,
decodeImage: () => Promise.resolve(),
media: createMemoryMediaCache(),
newViewerKey: () => "viewer-fixed-key-0001",
now: () => clock,
root,
setTimer: (run, delayMs) => {
const id = nextTimer;
nextTimer += 1;
timers.set(id, { at: clock + delayMs, run });
return id;
},
store: local,
});
}
/** One ordinary live run, so the display has a persisted snapshot to continue from, exactly as a
* screen that has been on the wall for a while does. */
async function runOnceLive(): Promise<void> {
const display = build();
await display.start();
await settle();
expect(root.dataset.offline).toBe("false");
await display.stop();
timers.clear();
}
it("registers once the server answers, after its first registration failed", async () => {
await runOnceLive();
server.sessionFailures = 1;
const sessionsBefore = server.sessionRequests;
const display = build();
await display.start();
await settle();
// Continuing from its own state while it cannot register: the honest banner.
expect(root.dataset.offline).toBe("true");
await advance(60_000);
expect(server.sessionRequests - sessionsBefore).toBeGreaterThanOrEqual(2);
expect(root.dataset.offline).toBe("false");
expect(subscriptions.length).toBeGreaterThanOrEqual(2);
await display.stop();
});
it("keeps retrying registration with backoff, and never gives up", async () => {
await runOnceLive();
server.sessionFailures = 8;
const sessionsBefore = server.sessionRequests;
const display = build();
await display.start();
await settle();
// Eight failures back off for at most 1 + 2 + 4 + 8 + 16 + 32 + 60 + 60 seconds, the last two at
// the one-minute ceiling. Five virtual minutes is enough for all of them and the success after.
await advance(5 * 60_000);
expect(server.sessionRequests - sessionsBefore).toBe(9);
expect(root.dataset.offline).toBe("false");
await display.stop();
});
it("retries a failed state refresh until the server answers, with no realtime nudge", async () => {
const display = build();
await display.start();
await settle();
expect(root.dataset.offline).toBe("false");
// The slot's deadline refresh fails, as it would mid-restart. Realtime says nothing.
server.stateFailing = true;
await advance(6_000);
expect(root.dataset.offline).toBe("true");
const failedRequests = server.stateRequests;
server.stateFailing = false;
await advance(120_000);
expect(server.stateRequests).toBeGreaterThan(failedRequests);
expect(root.dataset.offline).toBe("false");
await display.stop();
});
it("subscribes again when the host reports its realtime stream closed for good", async () => {
const display = build();
await display.start();
await settle();
expect(subscriptions).toHaveLength(1);
subscriptions[0]?.onStatus?.("closed");
await settle();
await advance(60_000);
expect(subscriptions.length).toBeGreaterThanOrEqual(2);
await display.stop();
});
it("schedules nothing after it is stopped", async () => {
await runOnceLive();
server.sessionFailures = 3;
const display = build();
await display.start();
await settle();
await display.stop();
const sessionsAtStop = server.sessionRequests;
await advance(5 * 60_000);
expect(server.sessionRequests).toBe(sessionsAtStop);
});
});
tests/browser/media-cache.test.ts
-119
View File
@@ -1,119 +0,0 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { createBrowserMediaCache, type SignageMediaCache } from "../../src/browser/storage.js";
/**
* The Cache Storage media cache hands out object URLs, and every live one pins its blob in the
* browser until it is revoked.
*
* Every state refresh looks up every cached slide, so a cache that minted a fresh URL per lookup
* leaked one blob per slide per refresh. In a real browser that exhausted blob storage within
* minutes: the display's own state requests then failed with `net::ERR_INSUFFICIENT_RESOURCES` and
* it fell back to its offline banner on a perfectly good network.
*/
/** Just enough Cache Storage: one named cache, keyed by request URL. */
function fakeCacheStorage() {
const entries = new Map<string, { body: ArrayBuffer; type: string }>();
const cache = {
async delete(request: Request | string): Promise<boolean> {
return entries.delete(typeof request === "string" ? request : request.url);
},
async keys(): Promise<Request[]> {
return [...entries.keys()].map((url) => new Request(url));
},
async match(request: Request | string): Promise<Response | undefined> {
const entry = entries.get(typeof request === "string" ? request : request.url);
return entry
? new Response(entry.body, { headers: { "content-type": entry.type } })
: undefined;
},
async put(request: Request | string, response: Response): Promise<void> {
entries.set(typeof request === "string" ? request : request.url, {
body: await response.arrayBuffer(),
type: response.headers.get("content-type") ?? "application/octet-stream",
});
},
};
return { open: async () => cache } as unknown as CacheStorage;
}
describe("Signage's media cache and object URLs", () => {
const realCreate = URL.createObjectURL;
const realRevoke = URL.revokeObjectURL;
let live: Set<string>;
let media: SignageMediaCache;
beforeEach(() => {
live = new Set();
let next = 0;
URL.createObjectURL = () => {
next += 1;
const url = `blob:test/${next}`;
live.add(url);
return url;
};
URL.revokeObjectURL = (url: string) => {
live.delete(url);
};
media = createBrowserMediaCache({
caches: fakeCacheStorage(),
fetch: async () =>
new Response(new Uint8Array([1, 2, 3]), { headers: { "content-type": "image/webp" } }),
location: { origin: "https://api.example.test" },
} as unknown as typeof globalThis);
});
afterEach(() => {
URL.createObjectURL = realCreate;
URL.revokeObjectURL = realRevoke;
});
const keys = ["slide/a", "slide/b", "slide/c"];
it("keeps one live object URL per cached slide, however often it is looked up", async () => {
for (const key of keys) {
await media.store(key, `https://files.example.test/${key}?sig=1`);
}
// A state refresh looks every slide up again; a long-running display does this for months.
for (let refresh = 0; refresh < 100; refresh += 1) {
for (const key of keys) {
await media.find(key);
}
}
expect(live.size).toBe(keys.length);
});
it("hands out the same URL for the same bytes", async () => {
await media.store("slide/a", "https://files.example.test/a?sig=1");
const first = await media.find("slide/a");
const second = await media.find("slide/a");
expect(first).toBeDefined();
expect(second).toBe(first);
});
it("revokes a pruned slide's URL", async () => {
for (const key of keys) {
await media.store(key, `https://files.example.test/${key}?sig=1`);
await media.find(key);
}
await media.prune(["slide/a"]);
expect(live.size).toBe(1);
expect(await media.find("slide/b")).toBeUndefined();
});
it("revokes the URL it replaces when a slide is stored again", async () => {
await media.store("slide/a", "https://files.example.test/a?sig=1");
await media.store("slide/a", "https://files.example.test/a?sig=2");
await media.find("slide/a");
expect(live.size).toBe(1);
});
it("releases every URL it handed out when the display stops", async () => {
for (const key of keys) {
await media.store(key, `https://files.example.test/${key}?sig=1`);
await media.find(key);
}
media.release();
expect(live.size).toBe(0);
});
});
tests/browser/support/fake-host.ts
+1 -1
View File
@@ -127,7 +127,7 @@ export function createFakeHost(options: FakeHostOptions): FakeHost {
/** The settings payload every screen loads first. */
export const FAKE_SETTINGS = Object.freeze({
crossfadeMs: 1000,
moduleVersion: "0.1.3",
moduleVersion: "0.1.1",
nativeImageDurationMs: 7000,
nativePresentation: {
backgroundColor: "#000000",
tests/drizzle-store.test.ts
-635
View File
@@ -1,635 +0,0 @@
import { isModuleDatabaseError, ModuleDatabaseError } from "@ekklesia/module-database";
import { moduleDrizzle } from "@ekklesia/module-database/drizzle";
import { describe, expect, it } from "vitest";
import { imageAssets } from "../src/schema/tables.js";
import { createSignageStore } from "../src/server/store/drizzle.js";
import {
type NewStoredImage,
type NewStoredSelection,
type NewStoredSlot,
type SignageStore,
SignageStoreConflict,
} from "../src/server/store/types.js";
import { type AbiResponder, createFakeAbiExecutor } from "./support/abi-executor.js";
/**
* Signage's production store over the platform's Module Database ABI v1 (platform ADR 0050).
*
* The executor double holds the store to the ABI's own rules (`./support/abi-executor.ts`), so what
* these prove is what Signage hands Core and how it reads Core's answers: SQL text, ABI parameters,
* positional rows of raw text forms, and callback-scoped transactions. The decisions above the store
* are proven against the in-memory store elsewhere.
*/
const GROUP = "00000000-0000-4000-8000-0000000000a1";
const CHANNEL = "00000000-0000-4000-8000-0000000000b1";
const FALLBACK_CHANNEL = "00000000-0000-4000-8000-0000000000b2";
const SELECTION = "00000000-0000-4000-8000-0000000000c1";
const TIMELINE = "00000000-0000-4000-8000-0000000000d1";
const SOURCE = "00000000-0000-4000-8000-0000000000e1";
const SLOT_1 = "00000000-0000-4000-8000-0000000000f1";
const SLOT_2 = "00000000-0000-4000-8000-0000000000f2";
const IMAGE = "00000000-0000-4000-8000-000000000101";
const INSTANT = new Date("2026-10-08T12:34:56.789Z");
/** How Core sends that instant: PostgreSQL's ISO output in UTC (ADR 0050's decoding table). */
const INSTANT_TEXT = "2026-10-08 12:34:56.789+00";
function image(): NewStoredImage {
return {
contentSha256: "a".repeat(64),
displayName: "Welcome",
encodedHeight: 1080,
encodedWidth: 1920,
expiresAt: INSTANT,
hasAlpha: false,
height: 1080,
id: IMAGE,
orientation: null,
originalByteSize: 5_000_000_000,
originalContentType: "image/png",
originalFilename: "welcome.png",
originalObjectKey: `originals/${IMAGE}`,
renditions: [
{
byteSize: 1234,
contentSha256: "b".repeat(64),
contentType: "image/webp",
height: 1080,
kind: "display",
objectKey: `renditions/${IMAGE}/display`,
width: 1920,
},
],
status: "ready",
width: 1920,
};
}
function selection(): NewStoredSelection {
return {
availableUntil: null,
deadlineAt: new Date(INSTANT.getTime() + 7_000),
durationMs: 7_000,
groupId: GROUP,
id: SELECTION,
itemId: IMAGE,
itemRevision: "1",
presentation: { tone: "warm" },
providerId: "signage.native-images",
rendererContributionId: null,
rendererContributionVersion: null,
selectionScope: null,
sequence: 9_007_199_254_740_000,
slotId: SLOT_1,
stale: false,
startedAt: INSTANT,
timelineId: TIMELINE,
variants: [
{ audienceKey: "default", isDefault: true, payload: { title: "Hello" } },
{ audienceKey: "online", isDefault: false, payload: "just text" },
],
withdrawn: false,
};
}
function slot(id: string): NewStoredSlot {
return {
durationOverrideMs: null,
eligibleFrom: null,
eligibleUntil: INSTANT,
enabled: true,
id,
itemId: IMAGE,
kind: "pinned-item",
presentation: {
backgroundColor: null,
backgroundDarkened: null,
backgroundMode: null,
blurPixels: null,
foregroundShadow: null,
},
providerId: "signage.native-images",
sourceId: null,
timelineId: TIMELINE,
};
}
/** Answers a select from a table with the given rows, and every other statement with none. */
function rowsFrom(tables: Readonly<Record<string, AbiResponder>>): AbiResponder {
return (statement) => tables[statement.summary]?.(statement);
}
function times(count: number, summary: string): string[] {
return Array.from({ length: count }, () => summary);
}
describe("Signage's production store over the Module Database ABI v1", () => {
it("reaches PostgreSQL only as SQL text, ABI parameters, and positional rows", async () => {
const fake = createFakeAbiExecutor();
await createSignageStore(fake.executor).listTimelines();
await createSignageStore(fake.executor).findViewerByKey("kiosk-1");
expect(fake.events).toEqual(["select signage_timelines", "select signage_viewers"]);
for (const statement of fake.statements) {
expect(statement.depth).toBe(0);
expect(statement.rowMode).toBe("array");
expect(statement.text).not.toContain("kiosk-1");
}
expect(fake.statements[1]?.values).toEqual(["kiosk-1"]);
});
it("encodes instants as ISO text and JSON as text, never as objects Core would refuse", async () => {
const fake = createFakeAbiExecutor();
await createSignageStore(fake.executor).insertSelection(selection());
const [selectionInsert, variantsInsert] = fake.statements;
expect(selectionInsert?.values).toContain("2026-10-08T12:34:56.789Z");
expect(selectionInsert?.values).toContain("2026-10-08T12:35:03.789Z");
expect(selectionInsert?.values).toContain('{"tone":"warm"}');
expect(selectionInsert?.values).toContain(9_007_199_254_740_000);
expect(variantsInsert?.values).toContain('{"title":"Hello"}');
expect(variantsInsert?.values).toContain('"just text"');
});
it("decodes the ABI's raw int8, timestamptz, and jsonb text into the values Signage reads", async () => {
const fake = createFakeAbiExecutor(
rowsFrom({
"select signage_channel_groups": () => [
{
created_at: INSTANT_TEXT,
id: GROUP,
name: "Sanctuary",
revision: 3,
updated_at: INSTANT_TEXT,
},
],
"select signage_channels": () => [
{ group_id: GROUP, id: CHANNEL, is_default: true, key: "default", name: "Default" },
],
"select signage_image_assets": () => [
{
content_sha256: "a".repeat(64),
created_at: "2026-10-08 12:00:00.123456+00",
display_name: "Welcome",
encoded_height: 1080,
encoded_width: 1920,
expires_at: null,
has_alpha: false,
height: 1080,
id: IMAGE,
orientation: 6,
original_byte_size: "5000000000",
original_content_type: "image/png",
original_filename: "welcome.png",
original_object_key: `originals/${IMAGE}`,
status: "ready",
width: 1920,
},
],
"select signage_image_renditions": () => [
{
asset_id: IMAGE,
byte_size: "1234",
content_sha256: "b".repeat(64),
content_type: "image/webp",
height: 1080,
kind: "display",
object_key: `renditions/${IMAGE}/display`,
width: 1920,
},
],
"select signage_playback_states": () => [
{
active_timeline_id: TIMELINE,
blackout: false,
current_selection_id: SELECTION,
current_slot_id: SLOT_1,
group_id: GROUP,
next_sequence: "42",
paused: false,
paused_remaining_ms: null,
pending_requested_at: null,
pending_timeline_id: null,
revision: 17,
scheduled_activation_at: "2026-10-09 07:30:00-05",
scheduled_timeline_id: TIMELINE,
slot_deadline_at: "2026-10-08 12:35:03.789+00",
slot_started_at: INSTANT_TEXT,
static_asset_id: null,
updated_at: INSTANT_TEXT,
},
],
"select signage_selection_variants": () => [
{
audience_key: "default",
id: "00000000-0000-4000-8000-000000000201",
is_default: true,
payload: '{"title":"Hello","lines":[1,2]}',
selection_id: SELECTION,
},
{
audience_key: "online",
id: "00000000-0000-4000-8000-000000000202",
is_default: false,
payload: '"123"',
selection_id: SELECTION,
},
],
"select signage_selections": () => [
{
available_until: null,
deadline_at: null,
duration_ms: 7000,
group_id: GROUP,
id: SELECTION,
item_id: IMAGE,
item_revision: "1",
presentation: '{"tone":"warm"}',
provider_id: "signage.native-images",
renderer_contribution_id: null,
renderer_contribution_version: null,
resolved_at: INSTANT_TEXT,
revision: 2,
selection_scope: null,
sequence: "9007199254740000",
slot_id: SLOT_1,
stale: false,
started_at: INSTANT_TEXT,
timeline_id: TIMELINE,
withdrawn: false,
},
],
"update signage_playback_states": () => [{ next_sequence: "43" }],
}),
);
const store = createSignageStore(fake.executor);
const group = await store.findChannelGroup(GROUP);
expect(group?.playback).toMatchObject({
nextSequence: 42,
revision: 17,
scheduledActivationAt: new Date("2026-10-09T12:30:00.000Z"),
slotDeadlineAt: new Date("2026-10-08T12:35:03.789Z"),
slotStartedAt: INSTANT,
updatedAt: INSTANT,
});
expect(group?.playback.slotStartedAt).toBeInstanceOf(Date);
expect(group?.channels).toEqual([
{ groupId: GROUP, id: CHANNEL, isDefault: true, key: "default", name: "Default" },
]);
const found = await store.findSelection(SELECTION);
expect(found).toMatchObject({
presentation: { tone: "warm" },
resolvedAt: INSTANT,
sequence: 9_007_199_254_740_000,
startedAt: INSTANT,
});
expect(found?.variants).toEqual([
{ audienceKey: "default", isDefault: true, payload: { lines: [1, 2], title: "Hello" } },
// A JSON string stays a string, even one that looks like a number.
{ audienceKey: "online", isDefault: false, payload: "123" },
]);
// `returning` rows decode the same way: the sequence this call owns is one below the new value.
await expect(store.takeSelectionSequence(GROUP)).resolves.toBe(42);
const [listed] = await store.listImages();
expect(listed).toMatchObject({
createdAt: new Date("2026-10-08T12:00:00.123Z"),
expiresAt: null,
orientation: 6,
originalByteSize: 5_000_000_000,
});
expect(listed?.renditions).toEqual([expect.objectContaining({ byteSize: 1234 })]);
});
});
describe("Signage's transactions over the ABI", () => {
const existingSlots = () => [
{ id: SLOT_1, position: 0 },
{ id: SLOT_2, position: 1 },
];
const flows: readonly {
readonly name: string;
readonly respond?: AbiResponder;
readonly run: (store: SignageStore) => Promise<unknown>;
readonly expected: readonly string[];
}[] = [
{
expected: ["insert signage_image_assets", "insert signage_image_renditions"],
name: "insertImage",
run: (store) => store.insertImage(image()),
},
{
expected: ["insert signage_channels", "update signage_channel_groups"],
name: "addChannel",
run: (store) =>
store.addChannel({
groupId: GROUP,
id: CHANNEL,
isDefault: false,
key: "online",
name: "Online",
}),
},
{
expected: [
"insert signage_channel_groups",
"insert signage_channels",
"insert signage_playback_states",
],
name: "createChannelGroup",
run: (store) =>
store.createChannelGroup({
channelId: CHANNEL,
channelName: "Default",
groupId: GROUP,
name: "Sanctuary",
}),
},
{
expected: [
"select signage_channels",
"update signage_viewers",
"delete signage_channel_groups",
],
name: "deleteChannelGroup",
respond: rowsFrom({ "select signage_channels": () => [{ id: CHANNEL }] }),
run: (store) => store.deleteChannelGroup(GROUP, FALLBACK_CHANNEL),
},
{
expected: ["insert signage_selections", "insert signage_selection_variants"],
name: "insertSelection",
run: (store) => store.insertSelection(selection()),
},
{
expected: [
"select signage_channels",
"delete signage_channels",
"update signage_channel_groups",
],
name: "removeChannel",
respond: rowsFrom({
"select signage_channels": () => [
{ group_id: GROUP, id: CHANNEL, is_default: false, key: "online", name: "Online" },
],
}),
run: (store) => store.removeChannel(CHANNEL),
},
{
expected: [
"update signage_selections",
"delete signage_selection_variants",
"insert signage_selection_variants",
],
name: "updateSelection",
run: (store) =>
store.updateSelection(SELECTION, {
bumpRevision: true,
stale: true,
variants: [{ audienceKey: "default", isDefault: true, payload: { title: "Again" } }],
}),
},
{
expected: [
"select signage_timeline_slots",
"insert signage_timeline_slots",
...times(6, "update signage_timeline_slots"),
"update signage_timelines",
],
name: "addSlot",
respond: rowsFrom({ "select signage_timeline_slots": existingSlots }),
run: (store) => store.addSlot({ ...slot("00000000-0000-4000-8000-0000000000f3") }, 1),
},
{
expected: [
"insert signage_timelines",
"insert signage_provider_sources",
"insert signage_timeline_slots",
],
name: "createTimeline",
run: (store) =>
store.createTimeline({
slots: [slot(SLOT_1)],
sources: [
{
id: SOURCE,
label: "Announcements",
providerId: "announcements",
selectionScope: "scope-1",
sourceId: "all",
timelineId: TIMELINE,
},
],
timeline: {
description: null,
eligibleFrom: INSTANT,
eligibleUntil: null,
id: TIMELINE,
name: "Sunday",
},
}),
},
{
expected: [
"select signage_timeline_slots",
"delete signage_timeline_slots",
"select signage_timeline_slots",
...times(2, "update signage_timeline_slots"),
"update signage_timelines",
],
name: "removeSlot",
respond: rowsFrom({
"select signage_timeline_slots": (statement) =>
statement.text.includes('"position"')
? [{ id: SLOT_2, position: 1 }]
: [{ timeline_id: TIMELINE }],
}),
run: (store) => store.removeSlot(SLOT_1),
},
{
expected: [
"select signage_provider_sources",
"delete signage_provider_sources",
"select signage_timeline_slots",
...times(4, "update signage_timeline_slots"),
"update signage_timelines",
],
name: "removeSource",
respond: rowsFrom({
"select signage_provider_sources": () => [{ timeline_id: TIMELINE }],
"select signage_timeline_slots": existingSlots,
}),
run: (store) => store.removeSource(SOURCE),
},
{
expected: [
"select signage_timeline_slots",
...times(4, "update signage_timeline_slots"),
"update signage_timelines",
],
name: "reorderSlots",
respond: rowsFrom({ "select signage_timeline_slots": existingSlots }),
run: (store) => store.reorderSlots(TIMELINE, [SLOT_2, SLOT_1]),
},
{
expected: [
"select signage_timeline_slots",
"update signage_timeline_slots",
"update signage_timelines",
],
name: "updateSlot",
respond: rowsFrom({ "select signage_timeline_slots": () => [{ timeline_id: TIMELINE }] }),
run: (store) => store.updateSlot(SLOT_1, { enabled: false, eligibleUntil: INSTANT }),
},
];
it("covers every transaction the store opens", () => {
// Thirteen `database.transaction` calls in src/server/store, none of them nested.
expect(flows.map((flow) => flow.name)).toHaveLength(13);
});
for (const flow of flows) {
it(`${flow.name} runs as one ABI transaction and commits`, async () => {
const fake = createFakeAbiExecutor(flow.respond);
await flow.run(createSignageStore(fake.executor));
expect(fake.events).toEqual(["BEGIN", ...flow.expected, "COMMIT"]);
// Every statement ran inside the transaction's own scope, and none opened a savepoint.
expect(fake.statements.every((statement) => statement.depth === 1)).toBe(true);
});
}
it("rolls back a refused default-channel removal and reports the conflict", async () => {
const fake = createFakeAbiExecutor(
rowsFrom({
"select signage_channels": () => [
{ group_id: GROUP, id: CHANNEL, is_default: true, key: "default", name: "Default" },
],
}),
);
await expect(createSignageStore(fake.executor).removeChannel(CHANNEL)).rejects.toMatchObject({
guarantee: "channel.default",
name: "SignageStoreConflict",
});
expect(fake.events).toEqual(["BEGIN", "select signage_channels", "ROLLBACK"]);
});
it("rolls back a slot order that is not exactly the timeline's slots", async () => {
const fake = createFakeAbiExecutor(
rowsFrom({ "select signage_timeline_slots": existingSlots }),
);
await expect(
createSignageStore(fake.executor).reorderSlots(TIMELINE, [SLOT_2]),
).rejects.toMatchObject({ guarantee: "timeline.slotOrder" });
expect(fake.events).toEqual(["BEGIN", "select signage_timeline_slots", "ROLLBACK"]);
});
it("rolls back the whole transaction when a later statement fails, and keeps that error", async () => {
const fake = createFakeAbiExecutor((statement) => {
if (statement.summary === "insert signage_selection_variants") {
throw new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23503" });
}
return [];
});
const failure = await createSignageStore(fake.executor)
.insertSelection(selection())
.then(
() => undefined,
(error: unknown) => error,
);
expect(fake.events).toEqual([
"BEGIN",
"insert signage_selections",
"insert signage_selection_variants",
"ROLLBACK",
]);
expect(failure).not.toBeInstanceOf(SignageStoreConflict);
expect((failure as Error).cause).toSatisfy(isModuleDatabaseError);
});
});
describe("a duplicate native image (SQLSTATE 23505)", () => {
function failingAssetInsert(error: Error) {
return createFakeAbiExecutor((statement) => {
if (statement.summary === "insert signage_image_assets") {
throw error;
}
return [];
});
}
it("reaches Signage wrapped by Drizzle, with the Ekklesia error as its cause", async () => {
// Why the old `error.code === "23505"` check never matched: Drizzle wraps whatever the driver,
// here the ABI executor, throws.
const fake = failingAssetInsert(
new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23505" }),
);
const failure = await moduleDrizzle(fake.executor)
.insert(imageAssets)
.values({ ...image(), renditions: undefined } as never)
.then(
() => undefined,
(error: unknown) => error as Error & { code?: unknown },
);
expect(failure?.name).not.toBe("ModuleDatabaseError");
expect(failure?.code).toBeUndefined();
expect(failure?.cause).toMatchObject({
code: "MODULE_DATABASE_QUERY_FAILED",
name: "ModuleDatabaseError",
sqlState: "23505",
});
});
it("is recognized through that wrapping and reported as Signage's content-hash conflict", async () => {
const fake = failingAssetInsert(
new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23505" }),
);
const failure = await createSignageStore(fake.executor)
.insertImage(image())
.then(
() => undefined,
(error: unknown) => error,
);
expect(failure).toBeInstanceOf(SignageStoreConflict);
expect((failure as SignageStoreConflict).guarantee).toBe("image.contentSha256");
expect(fake.events).toEqual(["BEGIN", "insert signage_image_assets", "ROLLBACK"]);
});
it.each([
[
"a foreign-key violation",
new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "23503" }),
],
["a failure with no SQLSTATE", new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED")],
["a refused parameter", new ModuleDatabaseError("MODULE_DATABASE_PARAMETER_INVALID")],
// A driver-shaped error is never what the ABI throws, and Signage no longer reads one.
["a raw pg-shaped error", Object.assign(new Error("duplicate key"), { code: "23505" })],
])("does not mistake %s for a duplicate", async (_name, error) => {
const fake = failingAssetInsert(error);
const failure = await createSignageStore(fake.executor)
.insertImage(image())
.then(
() => undefined,
(caught: unknown) => caught,
);
expect(failure).toBeInstanceOf(Error);
expect(failure).not.toBeInstanceOf(SignageStoreConflict);
expect((failure as Error).cause).toBe(error);
expect(fake.events.at(-1)).toBe("ROLLBACK");
});
});
tests/drizzle-timelines.test.ts
+3 -3
View File
@@ -1,4 +1,4 @@
import type { ModuleDrizzleDatabase } from "@ekklesia/module-database/drizzle";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { describe, expect, it } from "vitest";
import { createTimelineStore } from "../src/server/store/drizzle-timelines.js";
import type { NewStoredSlot } from "../src/server/store/types.js";
@@ -36,7 +36,7 @@ function slot(id: string): NewStoredSlot {
* actual database rejected a native-image slot before playback ever had content to resolve.
*/
function constraintDatabase(existing: readonly { id: string; position: number }[]): {
readonly database: ModuleDrizzleDatabase;
readonly database: ModuleDatabase;
readonly positions: number[];
} {
const positions: number[] = [];
@@ -66,7 +66,7 @@ function constraintDatabase(existing: readonly { id: string; position: number }[
return {
database: {
transaction: async (operation: (value: typeof transaction) => Promise<unknown>) => operation(transaction),
} as unknown as ModuleDrizzleDatabase,
} as unknown as ModuleDatabase,
positions,
};
}
tests/images.test.ts
-25
View File
@@ -1,4 +1,3 @@
import type { ModuleStorage } from "@ekklesia/module-sdk";
import sharp from "sharp";
import { beforeEach, describe, expect, it } from "vitest";
import { SignageError } from "../src/server/errors.js";
@@ -373,30 +372,6 @@ describe("native image ingest", () => {
expect(store.images.size).toBe(0);
});
it("recognizes a sanitized storage failure from the host's separate SDK copy", async () => {
const bucket = storage.bucket("native-images");
const externalError = Object.assign(new Error("The storage service could not be reached."), {
code: "STORAGE_PROVIDER_UNAVAILABLE",
name: "ModuleStorageError",
});
const externalStorage: ModuleStorage = {
bucket: () => ({ ...bucket, put: () => Promise.reject(externalError) }),
buckets: () => ["native-images"],
};
await expectSignageCode(
ingestNativeImage({
bytes: await makeImage({ format: "png", height: 360, width: 640 }),
displayName: "welcome.png",
expiresAt: null,
filename: "welcome.png",
storage: externalStorage,
store,
}),
"SIGNAGE_STORAGE_UNAVAILABLE",
);
});
it("treats a race with an identical upload as a success rather than a failure", async () => {
const bytes = await makeImage({ format: "png", height: 1080, width: 1920 });
const first = await ingest(bytes);
tests/manifest.test.ts
+5 -14
View File
@@ -63,19 +63,11 @@ describe("Signage module manifest", () => {
it("declares the module's product identity at the current manifest version", async () => {
const manifest = await readManifest();
expect(manifest.manifestVersion).toBe(8);
expect(manifest.manifestVersion).toBe(7);
expect(manifest.id).toBe("signage");
expect(manifest.name).toBe("Signage");
expect(manifest.version).toBe("0.1.3");
expect(manifest.compatibility).toEqual({ moduleSdk: "^0.2.0", platform: "^0.2.0" });
});
it("declares the Module Database ABI v1, so the platform hands it an executor and no ORM object", async () => {
const manifest = await readManifest();
// Platform ADR 0050: with `database.abi: 1`, `services.database` is the ABI v1 executor. Without
// it, a version 8 manifest would get the legacy Drizzle facade Signage no longer compiles against.
expect(manifest.database).toEqual({ abi: 1 });
expect(manifest.version).toBe("0.1.1");
expect(manifest.compatibility).toEqual({ moduleSdk: "^0.1.0", platform: "^0.1.0" });
});
it("declares every Signage permission, and none of them publicly", async () => {
@@ -150,8 +142,7 @@ describe("Signage module manifest", () => {
describe("Signage server runtime", () => {
it("exports the typed runtime definition the compiled server entrypoint publishes", async () => {
// The runtime's database declaration must match the manifest's, or Core refuses to start it.
expect(moduleRuntime).toMatchObject({ database: { abi: 1 }, id: "signage", version: "0.1.3" });
expect(moduleRuntime).toMatchObject({ id: "signage", version: "0.1.1" });
});
it("registers its routes declaratively, with no database, storage, or realtime work", async () => {
@@ -250,7 +241,7 @@ describe("Signage server runtime", () => {
expect(response.status).toBe(200);
expect(await response.json()).toEqual({
crossfadeMs: 400,
moduleVersion: "0.1.3",
moduleVersion: "0.1.1",
nativeImageDurationMs: 12_000,
nativePresentation: SIGNAGE_DEFAULT_SETTINGS.nativePresentation,
rendererInputVersion: "1.0.0",
tests/schema.test.ts
+2 -49
View File
@@ -7,12 +7,9 @@ import {
} from "@ekklesia/module-sdk";
import { getTableConfig, type PgTable } from "drizzle-orm/pg-core";
import { describe, expect, it } from "vitest";
import * as schemaEntrypoint from "../src/schema/index.js";
import * as schemaTables from "../src/schema/tables.js";
import moduleSchema from "../src/schema/index.js";
const moduleSchema = schemaEntrypoint.default;
/** Signage's own Drizzle tables, which only its store code uses. Core sees the metadata above. */
const tables: Readonly<Record<string, PgTable>> = schemaTables;
const tables = moduleSchema.tables as Readonly<Record<string, PgTable>>;
async function readSql(): Promise<string> {
return readFile(new URL("../drizzle/0000_initial.sql", import.meta.url), "utf8");
@@ -46,50 +43,6 @@ describe("Signage schema", () => {
expect(moduleSchema.moduleId).toBe("signage");
});
it("hands Core plain ABI v1 schema metadata: names and foreign-key targets, and no Drizzle object", () => {
// Platform ADR 0050: Core validates table ownership from plain data and never inspects an ORM
// object. The entrypoint's only export is that data.
expect(Object.keys(schemaEntrypoint)).toEqual(["default"]);
expect(JSON.parse(JSON.stringify(moduleSchema))).toEqual(moduleSchema);
const byName = [...moduleSchema.tables].sort((left, right) =>
left.name < right.name ? -1 : left.name > right.name ? 1 : 0,
);
expect(byName).toEqual([
{ name: "signage_channel_groups", foreignKeys: [] },
{ name: "signage_channels", foreignKeys: [{ table: "signage_channel_groups" }] },
{ name: "signage_image_assets", foreignKeys: [] },
{ name: "signage_image_renditions", foreignKeys: [{ table: "signage_image_assets" }] },
{
name: "signage_playback_states",
foreignKeys: [
{ table: "signage_channel_groups" },
{ table: "signage_timelines" },
{ table: "signage_timelines" },
{ table: "signage_image_assets" },
{ table: "signage_timelines" },
],
},
{ name: "signage_provider_sources", foreignKeys: [{ table: "signage_timelines" }] },
{ name: "signage_selection_variants", foreignKeys: [{ table: "signage_selections" }] },
{
name: "signage_selections",
foreignKeys: [{ table: "signage_channel_groups" }, { table: "signage_timeline_slots" }],
},
{
name: "signage_timeline_slots",
foreignKeys: [{ table: "signage_timelines" }, { table: "signage_provider_sources" }],
},
{ name: "signage_timelines", foreignKeys: [] },
{ name: "signage_viewers", foreignKeys: [{ table: "signage_channels" }] },
]);
// The same tables the store queries, derived rather than restated, so the two cannot drift.
expect(byName.map((table) => table.name)).toEqual(
Object.values(tables)
.map((table) => getTableConfig(table).name)
.sort(),
);
});
it("never points a foreign key outside this module", () => {
const owned = new Set(Object.values(tables).map((table) => getTableConfig(table).name));
tests/support/abi-executor.ts
-228
View File
@@ -1,228 +0,0 @@
import {
ModuleDatabaseError,
type ModuleDatabaseExecutor,
type ModuleDatabaseParameter,
type ModuleDatabaseQuery,
type ModuleDatabaseTransaction,
type ModuleDatabaseValue,
} from "@ekklesia/module-database";
/**
* A Module Database ABI v1 executor double (platform ADR 0050), for proving Signage's production
* store without PostgreSQL.
*
* It holds Signage to the rules the platform's real executor enforces, so a store change that would
* break against Core breaks here first:
*
* - parameters must be ABI values — a `Date` or a plain object is refused, exactly as Core refuses
* one, so an instant or a JSON payload the adapter failed to encode cannot slip through;
* - transactions and savepoints are callback scopes: committed only when the callback resolves with
* no work outstanding, rolled back when it rejects, and revoked once it settles;
* - only the innermost open scope may run statements;
* - after a failed statement the transaction is aborted, as in PostgreSQL, and cannot commit.
*
* Results are what Core sends: positional rows of the ABI's raw forms (`int8`, timestamps, and JSON
* as text). A responder answers each statement with rows keyed by column name; the double orders
* them by the statement's own select or returning list.
*/
export interface RecordedStatement {
readonly text: string;
readonly values: readonly ModuleDatabaseParameter[];
readonly rowMode: string;
/** 0 for an autocommit statement, 1 inside a transaction, 2 or more inside savepoints. */
readonly depth: number;
/** `select signage_timelines`, `insert signage_channels`, and so on. */
readonly summary: string;
}
export type AbiRow = Readonly<Record<string, ModuleDatabaseValue>>;
export type AbiResponder = (statement: RecordedStatement) => readonly AbiRow[] | undefined;
export interface FakeAbiExecutor {
readonly executor: ModuleDatabaseExecutor;
/** Every statement, in order, plus `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`, and
* `ROLLBACK TO SAVEPOINT` markers. */
readonly events: string[];
readonly statements: RecordedStatement[];
}
function isAbiParameter(value: unknown): value is ModuleDatabaseParameter {
if (value === null) {
return true;
}
if (Array.isArray(value)) {
return value.every(isAbiParameter);
}
return (
typeof value === "boolean" ||
typeof value === "number" ||
typeof value === "bigint" ||
typeof value === "string" ||
value instanceof Uint8Array
);
}
function summarize(text: string): string {
const verb = text.trimStart().split(/\s/u, 1)[0]?.toLowerCase() ?? "";
const target =
verb === "select"
? /\bfrom\s+"([^"]+)"/iu.exec(text)
: verb === "insert"
? /^\s*insert\s+into\s+"([^"]+)"/iu.exec(text)
: verb === "update"
? /^\s*update\s+"([^"]+)"/iu.exec(text)
: /^\s*delete\s+from\s+"([^"]+)"/iu.exec(text);
return `${verb} ${target?.[1] ?? "?"}`;
}
/** The column names a statement returns, in order: its select list, or its `returning` list. */
function resultColumns(text: string): string[] {
const list =
/^\s*select\s+(.*?)\s+from\s/isu.exec(text)?.[1] ?? /\sreturning\s+(.*)$/isu.exec(text)?.[1];
if (list === undefined) {
return [];
}
return list.split(",").map((column) => {
const names = [...column.matchAll(/"([^"]+)"/gu)].map((match) => match[1] ?? "");
return names.at(-1) ?? column.trim();
});
}
interface Scope {
closed: boolean;
active: boolean;
pending: number;
aborted: boolean;
}
export function createFakeAbiExecutor(respond: AbiResponder = () => []): FakeAbiExecutor {
const events: string[] = [];
const statements: RecordedStatement[] = [];
async function run(
scope: Scope,
transaction: Scope | undefined,
depth: number,
request: ModuleDatabaseQuery,
) {
if (scope.closed) {
throw new ModuleDatabaseError("MODULE_DATABASE_SCOPE_CLOSED");
}
if (!scope.active) {
throw new ModuleDatabaseError("MODULE_DATABASE_SCOPE_INACTIVE");
}
const values = request.values ?? [];
if (!values.every(isAbiParameter)) {
throw new ModuleDatabaseError("MODULE_DATABASE_PARAMETER_INVALID");
}
if (transaction?.aborted) {
// PostgreSQL's in_failed_sql_transaction.
throw new ModuleDatabaseError("MODULE_DATABASE_QUERY_FAILED", { sqlState: "25P02" });
}
const statement: RecordedStatement = {
depth,
rowMode: request.rowMode ?? "object",
summary: summarize(request.text),
text: request.text,
values,
};
statements.push(statement);
events.push(statement.summary);
scope.pending += 1;
try {
// Settle on a later event-loop turn, as a real round trip does, so a statement a callback
// forgot to await is still outstanding when that callback returns.
await new Promise<void>((resolve) => setImmediate(resolve));
let rows: readonly AbiRow[];
try {
rows = respond(statement) ?? [];
} catch (error) {
if (transaction) {
transaction.aborted = true;
}
throw error;
}
const columns = resultColumns(request.text);
return {
command: statement.summary.split(" ")[0]?.toUpperCase() ?? "",
fields: columns.map((name) => ({ name, typeOid: 25 })),
rowCount: rows.length,
rows:
statement.rowMode === "array"
? rows.map((row) => columns.map((column) => row[column] ?? null))
: rows,
};
} finally {
scope.pending -= 1;
}
}
async function runScope<T>(
parent: Scope,
transaction: Scope | undefined,
depth: number,
callback: (scope: ModuleDatabaseTransaction) => Promise<T> | T,
): Promise<T> {
const isTransaction = transaction === undefined;
const scope: Scope = { aborted: false, active: true, closed: false, pending: 0 };
const owner = transaction ?? scope;
const executor = Object.freeze({
abiVersion: 1 as const,
query: (request: ModuleDatabaseQuery) => run(scope, owner, depth, request),
savepoint: <S>(inner: (savepoint: ModuleDatabaseTransaction) => Promise<S> | S) => {
if (scope.closed) {
return Promise.reject(new ModuleDatabaseError("MODULE_DATABASE_SCOPE_CLOSED"));
}
if (!scope.active) {
return Promise.reject(new ModuleDatabaseError("MODULE_DATABASE_SCOPE_INACTIVE"));
}
return runScope(scope, owner, depth + 1, inner);
},
}) as unknown as ModuleDatabaseTransaction;
parent.active = false;
events.push(isTransaction ? "BEGIN" : "SAVEPOINT");
const abort = isTransaction ? "ROLLBACK" : "ROLLBACK TO SAVEPOINT";
try {
let value: T;
try {
value = await callback(executor);
} catch (error) {
events.push(abort);
throw error;
}
if (scope.pending > 0) {
events.push(abort);
throw new ModuleDatabaseError("MODULE_DATABASE_SCOPE_WORK_OUTSTANDING");
}
if (isTransaction && owner.aborted) {
events.push(abort);
throw new ModuleDatabaseError("MODULE_DATABASE_TRANSACTION_FAILED", { sqlState: "25P02" });
}
events.push(isTransaction ? "COMMIT" : "RELEASE");
return value;
} finally {
if (!isTransaction && events.at(-1) === abort) {
// A savepoint that rolled back leaves its transaction usable, as in PostgreSQL.
owner.aborted = false;
}
scope.closed = true;
parent.active = true;
}
}
const root: Scope = { aborted: false, active: true, closed: false, pending: 0 };
const executor = Object.freeze({
abiVersion: 1 as const,
query: (request: ModuleDatabaseQuery) => run(root, undefined, 0, request),
transaction: <T>(callback: (transaction: ModuleDatabaseTransaction) => Promise<T> | T) => {
// Top-level statements are autocommit and may run on other pooled connections, so the root
// executor stays usable while a transaction is open.
const detached: Scope = { aborted: false, active: true, closed: false, pending: 0 };
return runScope(detached, undefined, 1, callback);
},
}) as unknown as ModuleDatabaseExecutor;
return { events, executor, statements };
}
vitest.config.ts
+3 -3
View File
@@ -3,9 +3,9 @@ import { defineConfig } from "vitest/config";
/**
* Signage's own test configuration.
*
* It names both `.test.ts` and `.test.tsx` explicitly, because this module's browser tests are `.tsx`
* — they mount real React — and a test that is silently not run is the worst possible failure mode
* for a test suite. An empty run fails rather than passes.
* It exists because this module's browser tests are `.tsx` — they mount real React — and the
* repository root's configuration includes only `.test.ts`. Without this file those tests are
* silently not run, which is the worst possible failure mode for a test suite.
*/
export default defineConfig({
test: {