@intentius/chant-lexicon-fly 0.89.0 → 0.90.0

package/src/op/activities/index.ts

@@ -61,7 +61,10 @@ export {
   spriteRestore,
   listCheckpoints,
   spriteDestroy,
+  spriteDelete,
+  spriteUrl,
   resolveSpritesEndpoint,
+  resolveSpritesToken,
   defaultSpritesHttp,
   spriteCreateBody,
   parseCreateResponse,
@@ -84,8 +87,39 @@ export type {
   ListCheckpointsArgs,
   Checkpoint,
   SpriteDestroyArgs,
+  SpriteDeleteArgs,
+  SpriteUrlArgs,
+  SpriteUrlResult,
 } from "./sprites";
 
+// Sprite Services activities (#2711) — imperative create/get/list/start/stop/
+// delete/logs for one background service at a time, the single-service
+// primitives underneath `spriteApplyServices`'s batch reconcile.
+// `loadActivities(["fly"])` binds these; the step builders live in core.
+export {
+  spriteServiceCreate,
+  spriteServiceGet,
+  spriteServiceList,
+  spriteServiceStart,
+  spriteServiceStop,
+  spriteServiceDelete,
+  spriteServiceLogs,
+  spriteServiceCreateBody,
+  parseServiceLogNdjson,
+} from "./sprite-services";
+export type {
+  SpriteService,
+  SpriteServiceState,
+  SpriteServiceCreateArgs,
+  SpriteServiceGetArgs,
+  SpriteServiceListArgs,
+  SpriteServiceStartArgs,
+  SpriteServiceStopArgs,
+  SpriteServiceDeleteArgs,
+  SpriteServiceLogsArgs,
+  SpriteServiceLogsResult,
+} from "./sprite-services";
+
 // Sprite filesystem activities (#848) — imperative file I/O over the fs API.
 // `loadActivities(["fly"])` binds these; the step builders live in core.
 export {

package/src/op/activities/sprite-config.test.ts

@@ -107,6 +107,25 @@ describe("spriteApplyNetworkPolicy reconcile", () => {
       spriteApplyNetworkPolicy({ id: "np-1", rules: [{ domain: "", action: "allow" }], endpoint: fake.url }),
     ).rejects.toThrow(/missing domain/);
   });
+
+  // #2719: the real Sprites API and every official SDK (Go, JS, Python,
+  // Elixir) answer the policy update with 204 and no body; a 200 with the
+  // rules echoed back fails an SDK-backed client. Pin the fake's raw wire
+  // reply directly (spriteApplyNetworkPolicy itself tolerates any <300, so it
+  // wouldn't catch a regression here). GET is unchanged: 200 with the rules.
+  test("POST /policy/network answers 204 with no body; GET stays 200 with the rules", async () => {
+    await createImpl({ name: "np-wire", endpoint: fake.url });
+    const url = `${fake.url}/v1/sprites/np-wire/policy/network`;
+    const rules = [{ domain: "github.com", action: "allow" }];
+
+    const post = await fetch(url, { method: "POST", body: JSON.stringify({ rules }) });
+    expect(post.status).toBe(204);
+    expect(await post.text()).toBe("");
+
+    const get = await fetch(url);
+    expect(get.status).toBe(200);
+    expect(await get.json()).toEqual({ rules });
+  });
 });
 
 describe("spriteApplyServices reconcile", () => {

package/src/op/activities/sprite-services.docker.integration.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { spriteCreate, spriteDelete, spriteUrl } from "./sprites";
+import { spriteServiceCreate, spriteServiceStop, spriteServiceStart } from "./sprite-services";
+import { spritesContainerUp, spritesContainerDown } from "./sprites-emulator";
+
+// Acceptance (#2711) against the REAL spritzer image in container exec mode
+// (SPRITZER_EXEC=container, SPRITZER_RUNTIME=docker — INTENTIUS/spritzer#22):
+// create a sprite, create a service running `python3 -m http.server 8080`,
+// wait for its URL to answer, stop it (the URL stops answering), start it
+// again (the URL answers again), delete the sprite. `sprite-services.test.ts`
+// runs the same scenario against the in-process fake, no Docker. Docker
+// required; deterministically skipped in CI (GitHub runners have Docker, so
+// relying on absence would pull the image on every run) — run locally, or
+// opt in with SPRITES_DOCKER=1, same convention as the other docker tests
+// here.
+//
+// Cleanup: the sprite container spritzer makes (`spritzer-<name>`) is removed
+// by `spriteDelete` before spritzer itself comes down; `docker ps -a` after
+// this suite should show neither.
+
+const CONTAINER = "chant-spritzer-container-it";
+const PORT = 4294;
+const SPRITE = "chant-2711-web";
+
+let available = false;
+let endpoint = "";
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.SPRITES_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await spritesContainerUp({ name: CONTAINER, port: PORT, timeoutMs: 60_000 });
+    endpoint = up.endpoint;
+    prevBaseUrl = process.env.SPRITES_BASE_URL;
+    process.env.SPRITES_BASE_URL = endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 90_000);
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  if (available) {
+    // Idempotent: already deleted by the test on the happy path. A failed
+    // test still leaves no sprite container behind.
+    await spriteDelete({ id: SPRITE }).catch(() => {});
+    await spritesContainerDown({ name: CONTAINER });
+  }
+}, 30_000);
+
+describe("sprite services against real spritzer 0.6.0, container mode (#2711)", () => {
+  test("create → url waits and answers → stop → url stops answering → start → answers again → delete", async (ctx) => {
+    if (!available) ctx.skip();
+
+    await spriteCreate({ name: SPRITE });
+
+    await spriteServiceCreate({
+      id: SPRITE,
+      name: "web",
+      cmd: "python3",
+      args: ["-m", "http.server", "8080"],
+      http_port: 8080,
+      durationMs: 1000,
+    });
+
+    const { url } = await spriteUrl({ id: SPRITE, path: "/", timeoutMs: 20_000, intervalMs: 500 });
+    expect(url).toContain(SPRITE);
+
+    await spriteServiceStop({ id: SPRITE, name: "web" });
+    // The process is gone; nothing answers on the sprite URL any more.
+    const afterStop = await fetch(`${url}/`);
+    expect(afterStop.status).toBe(503);
+
+    await spriteServiceStart({ id: SPRITE, name: "web" });
+    const { url: url2 } = await spriteUrl({ id: SPRITE, path: "/", timeoutMs: 20_000, intervalMs: 500 });
+    expect(url2).toBe(url);
+
+    await spriteDelete({ id: SPRITE });
+    const afterDelete = await fetch(`${endpoint}/v1/sprites/${SPRITE}`);
+    expect(afterDelete.status).toBe(404);
+  }, 120_000);
+});

package/src/op/activities/sprite-services.test.ts

@@ -0,0 +1,263 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import type { SpritesHttp } from "./sprites";
+import { spriteCreate as createImpl } from "./sprites";
+import { createSpritesFake } from "./sprites-fake";
+import {
+  spriteServiceCreate,
+  spriteServiceGet,
+  spriteServiceList,
+  spriteServiceStart,
+  spriteServiceStop,
+  spriteServiceDelete,
+  spriteServiceLogs,
+  spriteServiceCreateBody,
+  parseServiceLogNdjson,
+} from "./sprite-services";
+
+// A recording HTTP stub: captures every call and answers from a callback.
+function recorder(answer: (method: string, url: string, body?: unknown) => { status: number; text: string }) {
+  const calls: Array<{ method: string; url: string; body?: unknown }> = [];
+  const http: SpritesHttp = async (method, url, body) => {
+    calls.push({ method, url, body });
+    return answer(method, url, body);
+  };
+  return { http, calls };
+}
+
+const running = (name: string, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name, cmd: "run", state: { name, status: "running", pid: 4321 }, ...extra });
+
+// ── Pure helpers ────────────────────────────────────────────────────────────
+
+describe("spriteServiceCreateBody", () => {
+  test("omits undefined optional fields", () => {
+    expect(spriteServiceCreateBody({ id: "s", name: "web", cmd: "run-web" })).toEqual({ cmd: "run-web" });
+  });
+
+  test("includes every field that is set", () => {
+    expect(
+      spriteServiceCreateBody({
+        id: "s",
+        name: "web",
+        cmd: "python3",
+        args: ["-m", "http.server", "8080"],
+        env: { PORT: "8080" },
+        dir: "/app",
+        needs: ["db"],
+        http_port: 8080,
+      }),
+    ).toEqual({
+      cmd: "python3",
+      args: ["-m", "http.server", "8080"],
+      env: { PORT: "8080" },
+      dir: "/app",
+      needs: ["db"],
+      http_port: 8080,
+    });
+  });
+});
+
+describe("parseServiceLogNdjson", () => {
+  test("keeps stdout/stderr data in order, drops the complete marker", () => {
+    const text = [
+      JSON.stringify({ type: "started", data: "web started (pid 1)" }),
+      JSON.stringify({ type: "stdout", data: "Serving on 0.0.0.0:8080" }),
+      JSON.stringify({ type: "complete", data: "ignored" }),
+    ].join("\n");
+    expect(parseServiceLogNdjson(text)).toEqual(["web started (pid 1)", "Serving on 0.0.0.0:8080"]);
+  });
+
+  test("skips blank and unparseable lines", () => {
+    expect(parseServiceLogNdjson('\n{"type":"stdout","data":"a"}\n\nnot json\n')).toEqual(["a"]);
+  });
+});
+
+// ── Activity request shapes (injected SpritesHttp) ─────────────────────────
+
+describe("spriteServiceCreate", () => {
+  test("PUTs .../services/{name} with ?duration, then GETs the definitive state", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: method === "PUT" ? 200 : 200,
+      text: method === "PUT" ? '{"type":"complete"}' : running("web", { http_port: 8080 }),
+    }));
+    const res = await spriteServiceCreate(
+      { id: "task-1", name: "web", cmd: "python3", args: ["-m", "http.server", "8080"], http_port: 8080, endpoint: "http://x" },
+      undefined,
+      http,
+    );
+    expect(res.state.status).toBe("running");
+    expect(calls[0].method).toBe("PUT");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1/services/web?duration=500ms");
+    expect(calls[0].body).toEqual({ cmd: "python3", args: ["-m", "http.server", "8080"], http_port: 8080 });
+    expect(calls[1].method).toBe("GET");
+    expect(calls[1].url).toBe("http://x/v1/sprites/task-1/services/web");
+  });
+
+  test("a custom durationMs is passed through as ms", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: running("web") }));
+    await spriteServiceCreate({ id: "t", name: "web", cmd: "x", durationMs: 2000, endpoint: "http://x" }, undefined, http);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web?duration=2000ms");
+  });
+
+  test("throws when the resulting state is failed", async () => {
+    const { http } = recorder((method) => ({
+      status: 200,
+      text: method === "PUT"
+        ? '{"type":"error","data":"boom"}'
+        : JSON.stringify({ name: "web", cmd: "x", state: { name: "web", status: "failed", error: "exec: not found" } }),
+    }));
+    await expect(
+      spriteServiceCreate({ id: "t", name: "web", cmd: "nope", endpoint: "http://x" }, undefined, http),
+    ).rejects.toThrow(/failed to start.*exec: not found/);
+  });
+
+  test("throws on a non-2xx PUT", async () => {
+    const { http } = recorder(() => ({ status: 400, text: "bad request" }));
+    await expect(
+      spriteServiceCreate({ id: "t", name: "web", cmd: "x", endpoint: "http://x" }, undefined, http),
+    ).rejects.toThrow(/create failed \(400\)/);
+  });
+});
+
+describe("spriteServiceGet", () => {
+  test("GETs .../services/{name}", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: running("web") }));
+    const res = await spriteServiceGet({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res.state.status).toBe("running");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web");
+  });
+});
+
+describe("spriteServiceList", () => {
+  test("GETs .../services and returns the array", async () => {
+    const list = [JSON.parse(running("web")), JSON.parse(running("db"))];
+    const { http, calls } = recorder(() => ({ status: 200, text: JSON.stringify(list) }));
+    const res = await spriteServiceList({ id: "t", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual(list);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services");
+  });
+});
+
+describe("spriteServiceStart / spriteServiceStop", () => {
+  test("start POSTs .../start?duration and re-GETs", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: 200,
+      text: method === "POST" ? '{"type":"complete"}' : running("web"),
+    }));
+    const res = await spriteServiceStart({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res.state.status).toBe("running");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/start?duration=500ms");
+  });
+
+  test("stop POSTs .../stop and re-GETs", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: 200,
+      text: method === "POST"
+        ? '{"type":"complete"}'
+        : JSON.stringify({ name: "web", cmd: "x", state: { name: "web", status: "stopped" } }),
+    }));
+    const res = await spriteServiceStop({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res.state.status).toBe("stopped");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/stop");
+  });
+
+  test("stop passes ?timeout when timeoutMs is set", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: 200,
+      text: method === "POST" ? "{}" : running("web"),
+    }));
+    await spriteServiceStop({ id: "t", name: "web", timeoutMs: 3000, endpoint: "http://x" }, undefined, http);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/stop?timeout=3000ms");
+  });
+});
+
+describe("spriteServiceDelete", () => {
+  test("DELETEs .../services/{name}", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: "{}" }));
+    await spriteServiceDelete({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(calls[0].method).toBe("DELETE");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web");
+  });
+
+  test("a 404 is idempotent, not an error", async () => {
+    const { http } = recorder(() => ({ status: 404, text: "gone" }));
+    await expect(spriteServiceDelete({ id: "t", name: "web", endpoint: "http://x" }, undefined, http)).resolves.toEqual({});
+  });
+});
+
+describe("spriteServiceLogs", () => {
+  test("GETs .../logs and returns the parsed tail", async () => {
+    const { http, calls } = recorder(() => ({
+      status: 200,
+      text: [JSON.stringify({ type: "stdout", data: "line 1" }), JSON.stringify({ type: "complete" })].join("\n"),
+    }));
+    const res = await spriteServiceLogs({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ lines: ["line 1"] });
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/logs");
+  });
+
+  test("passes ?lines when set", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: "" }));
+    await spriteServiceLogs({ id: "t", name: "web", lines: 5, endpoint: "http://x" }, undefined, http);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/logs?lines=5");
+  });
+});
+
+// ── End to end against the in-process fake (S7, no Docker) ────────────────
+//
+// The acceptance scenario from #2711, offline: create a sprite, create a
+// service with http_port, list/get it, stop and start it, delete it. The
+// docker-gated `sprite-services.docker.integration.test.ts` runs the same
+// scenario against real spritzer 0.6.0 in container mode.
+
+let fake: { url: string; close(): Promise<void> };
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+describe("sprite services against the in-process fake (#2711)", () => {
+  test("create, get, list, stop, start, delete", async () => {
+    await createImpl({ name: "svc-fake-1" });
+
+    const created = await spriteServiceCreate({
+      id: "svc-fake-1",
+      name: "web",
+      cmd: "python3",
+      args: ["-m", "http.server", "8080"],
+      http_port: 8080,
+    });
+    expect(created.state.status).toBe("running");
+
+    const got = await spriteServiceGet({ id: "svc-fake-1", name: "web" });
+    expect(got.name).toBe("web");
+    expect(got.http_port).toBe(8080);
+
+    const list = await spriteServiceList({ id: "svc-fake-1" });
+    expect(list.map((s) => s.name)).toEqual(["web"]);
+
+    const stopped = await spriteServiceStop({ id: "svc-fake-1", name: "web" });
+    expect(stopped.state.status).toBe("stopped");
+
+    const restarted = await spriteServiceStart({ id: "svc-fake-1", name: "web" });
+    expect(restarted.state.status).toBe("running");
+
+    const logs = await spriteServiceLogs({ id: "svc-fake-1", name: "web" });
+    expect(logs.lines.length).toBeGreaterThan(0);
+
+    await spriteServiceDelete({ id: "svc-fake-1", name: "web" });
+    await expect(spriteServiceGet({ id: "svc-fake-1", name: "web" })).rejects.toThrow(/get failed \(404\)/);
+
+    // A second delete is idempotent.
+    await expect(spriteServiceDelete({ id: "svc-fake-1", name: "web" })).resolves.toEqual({});
+  });
+});