pod-notifications
Use when watching Solid or LWS pod changes with @jeswr/pod-notifications, reconciling missed events, selecting push or polling, or managing subscription cleanup.
- License 许可
- MIT
- 所属仓库
- jeswr/solid-sdk
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- pod-notifications
- description
- Use when watching Solid or LWS pod changes with @jeswr/pod-notifications, reconciling missed events, selecting push or polling, or managing subscription cleanup.
02 资源文件 34
- 参考文档package.json1.9 KB
- 参考文档README.md14.5 KB
- 脚本src/channels/channel-url.ts1.6 KB
- 脚本src/channels/json-lines.test.ts2.8 KB
- 脚本src/channels/json-lines.ts1.2 KB
- 脚本src/channels/legacy-ws.ts375 B
- 脚本src/channels/lws-sse.ts363 B
- 脚本src/channels/lws-websocket.ts396 B
- 脚本src/channels/poll.test.ts13.2 KB
- 脚本src/channels/poll.ts6.1 KB
- 脚本src/channels/push.ts20.3 KB
- 脚本src/channels/relay-registration.ts2.2 KB
- 脚本src/channels/streaming-http.ts361 B
- 脚本src/channels/streaming-sse-legacy.test.ts25.0 KB
- 脚本src/channels/webhook-relay.test.ts17.7 KB
- 脚本src/channels/webhook-relay.ts385 B
- 脚本src/channels/websocket.test.ts37.5 KB
- 脚本src/channels/websocket.ts508 B
- 脚本src/channels/websocket2023.ts404 B
- 脚本src/client.test.ts27.6 KB
- 脚本src/client.ts4.0 KB
- 脚本src/index.ts332 B
- 脚本src/normalise.test.ts8.9 KB
- 脚本src/normalise.ts4.3 KB
- 脚本src/runtime.ts1.1 KB
- 脚本src/subscription.test.ts6.2 KB
- 脚本src/subscription.ts3.8 KB
- 脚本src/testing.test.ts2.5 KB
- 脚本src/testing.ts3.7 KB
- 脚本src/types.ts3.9 KB
- 脚本src/watch.test.ts19.7 KB
- 脚本src/watch.ts7.7 KB
- 参考文档tsconfig.json251 B
- 脚本vitest.config.ts524 B
03 SKILL.md 正文
<!-- AUTHORED-BY Codex GPT-6 --> <!-- AUTHORED-BY Codex GPT-6.1-Sol -->
@jeswr/pod-notifications
Quick reference
Create the client with auth.fetch from pod-auth and the storage
returned by createPodClient. It is scoped to one storage.
Notifications invalidate cached data; re-read through the storage API for authoritative state.
For view invalidation, prefer watchInvalidations({ fetch, topics, scope, onInvalidate, pollIntervalMs, signal, allowInsecureLoopback }). It returns an immediate { ready, close }
handle, discovers one storage and reuses that discovery for initial push. Pass a caller-owned
scope predicate over HTTP(S) URLs; WS(S) destinations are mapped to HTTP(S) before this check.
It bounds every fetch, notification service, stream/socket and cleanup URL, refuses redirects,
and retains URL syntax/HTTPS/loopback validation. Invalid arguments reject ready.
Own and close the handle even during pending discovery; callbacks are fenced after close.
First live, changes and resync invalidate; callbacks receive { type, object } hints.
Out-of-scope or unusable push, unsupported POSTs (404/405/410/501), missing WebSocket
(including legacy-ws) and missing LWS EventSource switch permanently to SDK polling.
Factories can supply absent browser constructors. Transient failures still reconnect with
fresh discovery. Multiple topics batch on LWS; Solid subscribes per topic. push: false
forces polling; pollIntervalMs: 0 disables all polling fallbacks. If discovery fails or
claims a storage that cannot contain the scoped topics, periodic full-refresh hints keep
already-readable resources current without repeating discovery. These hints pause offline
and resume at the next interval online. A discovery/read/push 403 terminates the watch;
cleanup DELETEs remain best effort. The optional storage
hint does not widen scope. See the README for the complete watcher contract and example.
import { createNotifications } from '@jeswr/pod-notifications';
import type { StorageClient } from '@jeswr/storage-client';
export async function watchCollection(
fetch: typeof globalThis.fetch,
storage: StorageClient,
hotResource: string,
invalidate: (url: string) => void,
reconcile: (since: Date) => void | Promise<void>,
reportError: (error: unknown) => void,
) {
const notifications = createNotifications({ fetch, storage });
const subscription = await notifications.subscribe([storage.root], {
depth: 'recursive',
hot: [hotResource],
pollIntervalMs: 30_000,
});
let closed = false;
let closing: Promise<void> | undefined;
let reconciliation = Promise.resolve();
let reconciling = false;
const pendingInvalidations = new Set<string>();
const stopChanges = subscription.on('change', event => {
if (closed) return;
const affected = new Set([event.object]);
if (event.type !== 'Update') {
affected.add(storage.root);
if (event.target) affected.add(event.target);
if (event.origin) affected.add(event.origin);
}
for (const url of affected) {
if (reconciling) pendingInvalidations.add(url);
else invalidate(url);
}
});
const reconcileSerially = (since: Date) => {
reconciliation = reconciliation.then(async () => {
if (closed) return;
reconciling = true;
try {
await reconcile(since);
} finally {
reconciling = false;
const affected = [...pendingInvalidations];
pendingInvalidations.clear();
if (!closed) for (const url of affected) invalidate(url);
}
});
return reconciliation;
};
const reconcileAfterEvent = async (since: Date) => {
try {
await reconcileSerially(since);
} catch (error) {
await close();
throw error;
}
};
const stopResync = subscription.on('resync', since => {
void reconcileAfterEvent(since).catch(reportError);
});
let sawLive = subscription.state === 'live';
const stopState = subscription.on('state', state => {
if (state === 'live' && !sawLive) {
sawLive = true;
void reconcileAfterEvent(new Date(0)).catch(reportError);
}
});
const close = () => {
if (!closing) {
closed = true;
pendingInvalidations.clear();
stopChanges();
stopResync();
stopState();
closing = subscription.close().finally(() => reconciliation.catch(() => {}));
}
return closing;
};
try {
// Seed immediately; polling resync and first live cover their setup gaps.
await reconcileSerially(new Date(0));
} catch (error) {
await close();
throw error;
}
return close;
}
Membership changes (Create, Delete, Move, Add, Remove) invalidate the object,
normalized target/origin containers and the watched root. The root covers missing
container hints; URL-keyed listings must refresh even when container ETags are absent.
Update invalidates its object. Outside reconciliation, each affected URL is invalidated
once per event. During reconciliation, invalidations are coalesced by URL and applied after
the read settles to discard any older snapshot it committed, even if the read failed.
Cleanup discards pending invalidations before waiting for the active read.
Own the returned async cleanup in the application lifecycle, including logout. subscribe
also accepts an abort signal. Alternatively iterate the subscription with for await; ending
an iterator detaches that iterator, so still close the subscription itself.
Cleanup fences queued reconciliation and waits for any running read to settle, even if closing
the subscription fails. Await it before clearing application state on logout.
subscribe() can return while push is still connecting. The first live transition does
not emit resync, so refresh again then to cover changes during setup. Polling emits a full
resync(new Date(0)) after its first successful baseline to cover the polling setup gap.
Initial reconciliation is awaited and failures close the subscription before rejecting
watchCollection. Later
reconciliation failures also close it and call the application's non-throwing reportError
handler; use that handler to show an error or arrange a retry. Initial, first-live and resync
reconciliations share a serial queue so an older read cannot overwrite a newer snapshot.
plan() is an I/O-free advertised preference, while subscription.channel reports the actual
transport. Supported push adapters are Solid WebSocketChannel2023 / StreamingHTTP, LWS
WebSocket / SSE / webhook relay, and NSS Updates-Via. LWS webhook delivery uses a registered
relay inbox and an SSE stream. Configure the relay origin and supply an application session adapter
getSessionIdToken(signal) that obtains a current ID token and honors cancellation:
import { createNotifications } from '@jeswr/pod-notifications';
import type { StorageClient } from '@jeswr/storage-client';
export function notificationsWithRelay(
authenticatedPodFetch: typeof globalThis.fetch,
storage: StorageClient,
getSessionIdToken: (signal: AbortSignal) => Promise<string>,
) {
return createNotifications({
fetch: authenticatedPodFetch,
storage,
relay: {
url: 'https://relay.example',
getIdToken: signal => getSessionIdToken(signal),
// fetch: relayFetch, // Optional separate transport; defaults to globalThis.fetch.
},
});
}
An actual webhook subscription requires relay.getIdToken; without it, a configured relay
still selects webhook-relay but stays degraded and retries. It does not fall back to polling.
Relay registration uses the ID token and a separate relay.fetch, never the pod access token
or authenticated pod fetch. Missing push support polls; pollIntervalMs: 0
disables that fallback and leaves the subscription degraded. Observe state for
connecting, live, degraded or terminal closed; polling is degraded by design.
depth is best effort, not a recursive crawler. LWS push retains server-recursive container
semantics. Solid container subscriptions and all polling observe direct membership; add
individual resources with hot to observe edits. Reconcile on resync after interruptions;
it supplies a timestamp, not a durable replay cursor. Polling establishes a quiet baseline
and emits Delete/Create when a watched topic disappears (404/410) or reappears after that
baseline, including resources without ETags. Missing ETags alone do not produce updates.
See LWS differences.
T-040 implements the ADR-005 contracts, createNotifications, internal createChangeNormalizer,
subscription lifecycle/async iteration, ./channels/poll, and ./testing fakes. T-041 adds
./channels/websocket2023 and ./channels/lws-websocket: Solid subscribes per topic, LWS
batches all topics. T-042 adds ./channels/streaming-http, ./channels/lws-sse and
./channels/legacy-ws. plan() reports advertised preference; WebSocket/SSE/legacy run push,
and T-043 adds ./channels/webhook-relay for registered LWS webhook delivery over relay SSE. The subscription's channel is the
actual transport. Keep that distinction explicit in the README.
Use only the storage-client public API (features, head, listAll, isWithinStorage,
createPodClient). WebSocket discovery uses a fresh isolated cache per attempt (the
invalidation watcher reuses its initial discovered client once), shared only
within that attempt's resolve/probe calls. Do not reach into backends or add a resolver dependency.
All topics/hot resources must be scoped. Poll serially, establish a quiet baseline, and commit
container snapshots only after all listing pages succeed. Missing ETags are not changes.
Polling containers cover direct membership; LWS push retains recursive server semantics.
Hot resources observe individual edits. Offline pauses
and aborts work; online immediately reconciles. Forbidden closes; transient failures retry.
Close must release timers/listeners and settle pending iterators even when observers fail.
SubscriptionController, runtime.ts and channels/push.ts are internal shared seams; maintain
terminal closed state and idempotent cleanup. Do not run polling and push for the same topic.
WebSocket close/error/90-second inactivity reconnects every topic together, with fresh discovery
and POSTs. Full jitter uses a 1-second floor and a capped exponential ceiling of 60 seconds;
reset only once all sockets open. Emit resync(sinceLastFrame) after interruptions, using
the earliest per-socket timestamp and retaining it through partial reconnects. Offline
aborts and suspends; online immediately rediscovers. Any discovery/subscribe 403 closes with
forbidden. Detach listeners before closing sockets; ignore stale callbacks/responses and
delete late subscriptions. close() awaits best-effort DELETEs already in flight. Solid
channel id/@id cleanup requires the subscription service's origin and caller scope;
ignore missing or unsafe optional ids without disrupting delivery. Expiry is the fallback.
Validate all HTTP destinations and returned URLs before I/O: HTTPS/WSS, credential/fragment/
control-free, receive/delete hosts equal storage or subscription service (including port).
allowInsecureLoopback defaults false; HTTP/WS requires literal loopback at both ends.
Never print token-bearing channel URLs. Leave solid-offline's implementation intact for T-062.
StreamingHTTP uses one POST and fetch stream per Solid topic. Keep the UTF-8 decoder state across chunks, parse complete LF/CRLF JSON lines, flush a final unterminated record and bound records to 1,048,576 UTF-16 code units. Skip blank/malformed JSON; decoding errors, oversize, EOF and read errors reconnect with fresh discovery and resync. Register reader cancellation before emitting live; observer-driven close and stale reads cannot leak changes or retries. LWS SSE batches topics into one SseSubscription and uses native EventSource reconnection: retain the source on readyState=0 errors so Last-Event-ID survives, degrade until open, then resync. Factories must implement native auto-retry and id-buffer semantics. On terminal errors/close, rediscover and re-subscribe with SDK backoff. Close/offline detaches and closes sources and DELETEs LWS subscriptions. Native EventSource owns recoverable retry timing. NSS rediscovers Updates-Via, restricts socket hosts to storage, uses solid-0.1 and sends one sub frame per deduplicated topic. Only exact pub frames for subscribed topics produce Update; validate topic syntax before constructing frames. Never interpret protocol banners as changes.
Normalisation takes a canonical storage id separately from the URL scope predicate (LWS id and root may differ). Do not fetch JSON-LD contexts. Scope-filter objects before dedupe and scope-filter optional target/origin URLs. Never log raw frames or untrusted URL credentials. Dedupe is per normalizer, by accepted publisher-supplied id, expiring at exactly five seconds. Give each activity without a usable publisher id a fresh id within that normalizer; always deliver it, even when its object, timestamp and other fields match another activity.
./testing provides fake timers, sockets and event sources without network or Node-only
imports. Advance fake timers asynchronously to await complete channel cycles. Keep transport
factories and clocks injectable; WebSockets consume socket/random hooks; LWS SSE consumes
event sources. FakeEventSource.reconnect() models native Last-Event-ID replay without
replacing the instance.
Before implementation, read SDK core ADR-001 D4 and ADR-005-live-updates.md in
solid-suite-planning/specs/sdk-core/, alongside this repository's AGENTS.md.
This package is security critical. Keep coverage thresholds at 100% and add behavioral and
adversarial tests with every behavior change. Keep development tool versions aligned with
the root manifest. The pinned pnpm 10.4.1 with ignore-scripts requires local tool declarations
for filtered scripts. Validate with this package's lint, dependency-first build, typecheck and
test scripts, and the repository gate.
T-043 registers the canonical storage id using relay.getIdToken(signal) and a separate
relay.fetch (default global fetch). Never send pod access tokens through the relay
transport. Relay base URLs are explicit origins; validate scheme/credentials/controls,
returned id/token, and the exact inbox path before subscribing. The relay stream URL is
constructed locally. Reuse native SSE retry/Last-Event-ID and terminal rediscovery behavior.
Webhook subscriptions batch all topics, select the WebhookSubscription service even when
another push service is preferred, retain DELETE cleanup, and report webhook-relay as via.
A relay registration 403 closes forbidden. The optional ID-token callback preserves existing
plan() configuration, but an actual webhook subscription requires it.
04 同仓库更多 Skills
storage-conformance
Work on @jeswr/storage-conformance, the shared storage conformance suite package in the Solid SDK workspace.
fetch-rdf-engine-tests
Maintain fetch-rdf's real Node WASM parser integration tests without introducing a reverse engine dependency in fetch-rdf.
alpha
Use when checking fixtures, including folded YAML descriptions.
widget
Use when testing package skills: YAML quoting works.
web-seo
Use when improving technical and entity SEO for a modern personal, portfolio, documentation, or marketing site, including crawlable HTML, canonical metadata, sitemap and robots, Person/ProfilePage JSON-LD, Core Web Vitals, and honest ranking expectations.
solid-wac
Use when implementing or auditing Solid server WAC authorization, ACL creation and inheritance, auxiliary-resource escalation, method-to-mode mapping, 401 versus 403 challenges, WAC-Allow, or defensive typed ACL parsing with @solid/object and @rdfjs/wrapper.