@crvouga/mockingbird-service-fcm 2.1.0 → 2.3.0

package/DISCOVERY.md

@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
 designed for assertions and diagnosis by consuming test suites.
 
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,

package/README.md

@@ -20,36 +20,36 @@ ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with `npx m
 `firebase-admin` hardcodes `https://fcm.googleapis.com`. Point it at the emulator with `createAdminTransport` (an `https.Agent` that dials the emulator) and call `enableLegacyHttpTransport()` so multicast sends honor that agent. `send` is already HTTP/1.1. The fixture project is `demo-project`, the fixture device token is `fixture-device-token`, and any bearer is accepted until you turn on `strict`.
 
 ```ts
+import { deleteApp, initializeApp } from "firebase-admin/app"
+import { getMessaging } from "firebase-admin/messaging"
 import { createServer } from "@crvouga/mockingbird-service-fcm/server"
 import { createAdminTransport } from "@crvouga/mockingbird-service-fcm/admin"
 
+// Test setup: the emulator, plus a credential and an agent that reach it.
 const fcm = await createServer()
 const transport = await createAdminTransport({ origin: fcm.url, token: "fixture-token" })
-// initializeApp({ projectId: "demo-project", credential: transport.credential, httpAgent: transport.agent })
-// getMessaging(app).enableLegacyHttpTransport()
-await transport.close()
-await fcm.close()
-```
-
-Without the SDK, `POST` the wire body and read the outbox:
 
-```ts
-import { createRuntime, FCM_FIXTURE_PROJECT, FCM_FIXTURE_TOKEN } from "@crvouga/mockingbird-service-fcm"
-
-const fcm = createRuntime()
-const response = await fcm.fetch(
-  new Request(`http://fcm.test/v1/projects/${FCM_FIXTURE_PROJECT}/messages:send`, {
-    method: "POST",
-    headers: { authorization: "Bearer fixture-token", "content-type": "application/json" },
-    body: JSON.stringify({
-      message: { token: FCM_FIXTURE_TOKEN, notification: { title: "Hello", body: "World" } },
-    }),
-  }),
-)
-const body = (await response.json()) as { name: string }
-const outbox = await (await fcm.fetch(new Request("http://fcm.test/__admin/outbox"))).json()
-void body
+// The application's firebase-admin app. Only its credential and httpAgent change.
+const app = initializeApp({
+  projectId: "demo-project",
+  credential: transport.credential,
+  httpAgent: transport.agent,
+})
+const messaging = getMessaging(app)
+messaging.enableLegacyHttpTransport()
+const name = await messaging.send({
+  token: "fixture-device-token",
+  notification: { title: "Hello", body: "World" },
+})
+// name → "projects/demo-project/messages/<id>"
+
+// Test control: every message the emulator accepted.
+const outbox = await (await fetch(`${fcm.url}/__admin/outbox`)).json()
 void outbox
+
+await deleteApp(app)
+await transport.close()
+await fcm.close()
 ```
 
 ### Routes

package/dist/admin.js

@@ -1,6 +1,6 @@
 import {
   fcmCredential
-} from "./chunk-K7GBD2SV.js";
+} from "./chunk-5RVPNZ5C.js";
 
 // src/admin.ts
 import { Agent, createServer } from "node:https";