Archived
refactor(cli): define canonical native service plans
This commit is contained in:
Federico Jaramillo Martinez
@@ -0,0 +1,356 @@
|
|||||||
|
import { describe, expect, it, vi } from "vitest";
|
||||||
|
import {
|
||||||
|
createDevelopmentNativeServicePlan,
|
||||||
|
planValidationProbeRequests,
|
||||||
|
resolveProductionNativeServicePlan,
|
||||||
|
type NativeServiceAuthoritativeProbe,
|
||||||
|
type NativeServiceProbeRequest,
|
||||||
|
type NativeServiceProbeResult,
|
||||||
|
type ProductionNativeServicePlanInput,
|
||||||
|
} from "./servicePlan.js";
|
||||||
|
|
||||||
|
const backend = { kind: "systemd", label: "systemd user services" } as const;
|
||||||
|
const shell = {
|
||||||
|
name: "zsh",
|
||||||
|
executable: "/bin/zsh",
|
||||||
|
source: "detected",
|
||||||
|
detectedExecutable: "/bin/zsh",
|
||||||
|
} as const;
|
||||||
|
|
||||||
|
function productionInput(): ProductionNativeServicePlanInput {
|
||||||
|
return {
|
||||||
|
backend,
|
||||||
|
shell,
|
||||||
|
environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
|
||||||
|
executables: {
|
||||||
|
sessiond: {
|
||||||
|
configuredCommand: undefined,
|
||||||
|
namedCommand: "pi-web-sessiond",
|
||||||
|
bundledEntrypointPath: "/package/dist/server/sessiond.js",
|
||||||
|
},
|
||||||
|
web: {
|
||||||
|
configuredCommand: undefined,
|
||||||
|
namedCommand: "pi-web-server",
|
||||||
|
bundledEntrypointPath: "/package/dist/server/index.js",
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function completedProbe(status: "satisfied" | "unsatisfied", detail: string | null = null): NativeServiceAuthoritativeProbe {
|
||||||
|
return {
|
||||||
|
run: (request) => Promise.resolve({
|
||||||
|
kind: "completed",
|
||||||
|
outcomes: request.prerequisites.map((prerequisite) => ({ prerequisiteId: prerequisite.id, status, detail })),
|
||||||
|
}),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
describe("production native service planning", () => {
|
||||||
|
it("selects named commands from one authoritative backend probe and carries their exact requirements", async () => {
|
||||||
|
const requests: NativeServiceProbeRequest[] = [];
|
||||||
|
const probe: NativeServiceAuthoritativeProbe = {
|
||||||
|
run: (request) => {
|
||||||
|
requests.push(request);
|
||||||
|
return Promise.resolve({
|
||||||
|
kind: "completed",
|
||||||
|
outcomes: request.prerequisites.map((prerequisite) => ({
|
||||||
|
prerequisiteId: prerequisite.id,
|
||||||
|
status: "satisfied",
|
||||||
|
detail: "/usr/local/bin/example",
|
||||||
|
})),
|
||||||
|
});
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const resolution = await resolveProductionNativeServicePlan(productionInput(), {
|
||||||
|
probe,
|
||||||
|
fileExists: () => false,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(requests).toEqual([
|
||||||
|
{
|
||||||
|
purpose: "executable-selection",
|
||||||
|
backend,
|
||||||
|
shell,
|
||||||
|
environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
|
||||||
|
workingDirectory: null,
|
||||||
|
prerequisites: [
|
||||||
|
expect.objectContaining({ id: "sessiond.command.pi-web-sessiond", kind: "command-available", command: "pi-web-sessiond" }),
|
||||||
|
expect.objectContaining({ id: "web.command.pi-web-server", kind: "command-available", command: "pi-web-server" }),
|
||||||
|
],
|
||||||
|
},
|
||||||
|
]);
|
||||||
|
expect(resolution.ok).toBe(true);
|
||||||
|
if (!resolution.ok) throw new Error(JSON.stringify(resolution.failures));
|
||||||
|
|
||||||
|
expect(resolution.plan).toMatchObject({
|
||||||
|
mode: "production",
|
||||||
|
backend,
|
||||||
|
shell,
|
||||||
|
services: [
|
||||||
|
{
|
||||||
|
id: "sessiond",
|
||||||
|
manager: { systemdName: "pi-web-sessiond.service", launchdLabel: "com.pi-web.sessiond" },
|
||||||
|
shellCommand: "exec pi-web-sessiond",
|
||||||
|
strategy: { kind: "named-command", command: "pi-web-sessiond", selectedBy: "authoritative-backend-probe" },
|
||||||
|
environment: { PI_WEB_CONFIG: "/home/user/.config/pi-web/config.json" },
|
||||||
|
workingDirectory: null,
|
||||||
|
after: [],
|
||||||
|
wants: [],
|
||||||
|
prerequisites: [
|
||||||
|
{ id: "sessiond.command.pi-web-sessiond", kind: "command-available", command: "pi-web-sessiond" },
|
||||||
|
{ id: "sessiond.node", kind: "node-version", command: "node", minimumMajor: 22 },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: "web",
|
||||||
|
shellCommand: "exec pi-web-server",
|
||||||
|
strategy: { kind: "named-command", command: "pi-web-server" },
|
||||||
|
after: ["sessiond"],
|
||||||
|
wants: ["sessiond"],
|
||||||
|
prerequisites: [
|
||||||
|
{ id: "web.command.pi-web-server", kind: "command-available", command: "pi-web-server" },
|
||||||
|
{ id: "web.node", kind: "node-version", command: "node", minimumMajor: 22 },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(planValidationProbeRequests(resolution.plan)).toMatchObject([
|
||||||
|
{
|
||||||
|
purpose: "plan-validation",
|
||||||
|
backend,
|
||||||
|
shell,
|
||||||
|
workingDirectory: null,
|
||||||
|
prerequisites: [{ id: "sessiond.command.pi-web-sessiond" }, { id: "sessiond.node" }],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
purpose: "plan-validation",
|
||||||
|
backend,
|
||||||
|
shell,
|
||||||
|
workingDirectory: null,
|
||||||
|
prerequisites: [{ id: "web.command.pi-web-server" }, { id: "web.node" }],
|
||||||
|
},
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("preserves configured overrides verbatim and never probes or executes them", async () => {
|
||||||
|
const input = productionInput();
|
||||||
|
input.executables.sessiond.configuredCommand = " /opt/pi web/run-sessiond --flag ";
|
||||||
|
input.executables.web.configuredCommand = "custom-web --serve";
|
||||||
|
const run = vi.fn<(request: NativeServiceProbeRequest) => Promise<NativeServiceProbeResult>>();
|
||||||
|
const fileExists = vi.fn<(path: string) => boolean>();
|
||||||
|
|
||||||
|
const resolution = await resolveProductionNativeServicePlan(input, { probe: { run }, fileExists });
|
||||||
|
|
||||||
|
expect(run).not.toHaveBeenCalled();
|
||||||
|
expect(fileExists).not.toHaveBeenCalled();
|
||||||
|
expect(resolution.ok).toBe(true);
|
||||||
|
if (!resolution.ok) throw new Error(JSON.stringify(resolution.failures));
|
||||||
|
expect(resolution.plan.services).toMatchObject([
|
||||||
|
{
|
||||||
|
id: "sessiond",
|
||||||
|
shellCommand: "exec /opt/pi web/run-sessiond --flag ",
|
||||||
|
strategy: {
|
||||||
|
kind: "configured-override",
|
||||||
|
command: " /opt/pi web/run-sessiond --flag ",
|
||||||
|
verification: "unverified",
|
||||||
|
},
|
||||||
|
prerequisites: [],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: "web",
|
||||||
|
shellCommand: "exec custom-web --serve",
|
||||||
|
strategy: { kind: "configured-override", command: "custom-web --serve", verification: "unverified" },
|
||||||
|
prerequisites: [],
|
||||||
|
},
|
||||||
|
]);
|
||||||
|
expect(planValidationProbeRequests(resolution.plan)).toEqual([]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("falls back per service to bundled entrypoints when named commands are unavailable", async () => {
|
||||||
|
const input = productionInput();
|
||||||
|
input.executables.sessiond.bundledEntrypointPath = "/package with space/sessiond's entry.js";
|
||||||
|
const fileExists = vi.fn<(path: string) => boolean>(() => true);
|
||||||
|
|
||||||
|
const resolution = await resolveProductionNativeServicePlan(input, {
|
||||||
|
probe: completedProbe("unsatisfied", "command not found"),
|
||||||
|
fileExists,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(fileExists).toHaveBeenCalledTimes(2);
|
||||||
|
expect(resolution.ok).toBe(true);
|
||||||
|
if (!resolution.ok) throw new Error(JSON.stringify(resolution.failures));
|
||||||
|
expect(resolution.plan.services[0]).toMatchObject({
|
||||||
|
shellCommand: "exec node '/package with space/sessiond'\\''s entry.js'",
|
||||||
|
strategy: {
|
||||||
|
kind: "bundled-entrypoint",
|
||||||
|
command: "node",
|
||||||
|
namedCommand: "pi-web-sessiond",
|
||||||
|
namedCommandFailure: "command not found",
|
||||||
|
},
|
||||||
|
prerequisites: [
|
||||||
|
{ id: "sessiond.node", kind: "node-version", command: "node", minimumMajor: 22 },
|
||||||
|
{ id: "sessiond.entrypoint", kind: "readable-file", path: "/package with space/sessiond's entry.js" },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it("mixes configured, named, and bundled decisions without unrelated checks", async () => {
|
||||||
|
const input = productionInput();
|
||||||
|
input.executables.sessiond.configuredCommand = "custom-sessiond";
|
||||||
|
const requests: NativeServiceProbeRequest[] = [];
|
||||||
|
|
||||||
|
const resolution = await resolveProductionNativeServicePlan(input, {
|
||||||
|
probe: {
|
||||||
|
run: (request) => {
|
||||||
|
requests.push(request);
|
||||||
|
return Promise.resolve({
|
||||||
|
kind: "completed",
|
||||||
|
outcomes: [{ prerequisiteId: "web.command.pi-web-server", status: "unsatisfied", detail: null }],
|
||||||
|
});
|
||||||
|
},
|
||||||
|
},
|
||||||
|
fileExists: () => true,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(requests[0]?.prerequisites).toMatchObject([{ id: "web.command.pi-web-server", command: "pi-web-server" }]);
|
||||||
|
expect(resolution.ok).toBe(true);
|
||||||
|
if (resolution.ok) {
|
||||||
|
expect(resolution.plan.services.map((service) => service.strategy.kind)).toEqual(["configured-override", "bundled-entrypoint"]);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it("returns structured failures when neither production executable strategy is viable", async () => {
|
||||||
|
const resolution = await resolveProductionNativeServicePlan(productionInput(), {
|
||||||
|
probe: completedProbe("unsatisfied", "not found in service PATH"),
|
||||||
|
fileExists: () => false,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(resolution).toEqual({
|
||||||
|
ok: false,
|
||||||
|
failures: [
|
||||||
|
{
|
||||||
|
kind: "executable-unavailable",
|
||||||
|
serviceId: "sessiond",
|
||||||
|
namedCommand: "pi-web-sessiond",
|
||||||
|
namedCommandFailure: "not found in service PATH",
|
||||||
|
bundledEntrypointPath: "/package/dist/server/sessiond.js",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
kind: "executable-unavailable",
|
||||||
|
serviceId: "web",
|
||||||
|
namedCommand: "pi-web-server",
|
||||||
|
namedCommandFailure: "not found in service PATH",
|
||||||
|
bundledEntrypointPath: "/package/dist/server/index.js",
|
||||||
|
},
|
||||||
|
],
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does not reinterpret probe infrastructure failures as missing commands", async () => {
|
||||||
|
const fileExists = vi.fn<(path: string) => boolean>(() => true);
|
||||||
|
const resolution = await resolveProductionNativeServicePlan(productionInput(), {
|
||||||
|
probe: {
|
||||||
|
run: () => Promise.resolve({ kind: "infrastructure-failure", message: "launchd probe cleanup failed" }),
|
||||||
|
},
|
||||||
|
fileExists,
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(fileExists).not.toHaveBeenCalled();
|
||||||
|
expect(resolution).toEqual({
|
||||||
|
ok: false,
|
||||||
|
failures: [{
|
||||||
|
kind: "probe-infrastructure",
|
||||||
|
serviceIds: ["sessiond", "web"],
|
||||||
|
message: "launchd probe cleanup failed",
|
||||||
|
}],
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it("treats thrown and malformed probe results as infrastructure failures", async () => {
|
||||||
|
const thrown = await resolveProductionNativeServicePlan(productionInput(), {
|
||||||
|
probe: { run: () => Promise.reject(new Error("systemd-run failed")) },
|
||||||
|
fileExists: () => true,
|
||||||
|
});
|
||||||
|
expect(thrown).toMatchObject({
|
||||||
|
ok: false,
|
||||||
|
failures: [{ kind: "probe-infrastructure", message: "systemd-run failed" }],
|
||||||
|
});
|
||||||
|
|
||||||
|
const malformed = await resolveProductionNativeServicePlan(productionInput(), {
|
||||||
|
probe: {
|
||||||
|
run: () => Promise.resolve({
|
||||||
|
kind: "completed",
|
||||||
|
outcomes: [{ prerequisiteId: "sessiond.command.pi-web-sessiond", status: "satisfied", detail: null }],
|
||||||
|
}),
|
||||||
|
},
|
||||||
|
fileExists: () => true,
|
||||||
|
});
|
||||||
|
expect(malformed).toMatchObject({
|
||||||
|
ok: false,
|
||||||
|
failures: [{ kind: "probe-infrastructure", message: "Authoritative probe returned no outcome for web.command.pi-web-server." }],
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("development native service planning", () => {
|
||||||
|
it("plans only the exact checkout commands and prerequisites", () => {
|
||||||
|
const plan = createDevelopmentNativeServicePlan({
|
||||||
|
backend: { kind: "launchd", label: "LaunchAgents" },
|
||||||
|
shell: { name: "fish", executable: "/opt/homebrew/bin/fish", source: "detected", detectedExecutable: "/opt/homebrew/bin/fish" },
|
||||||
|
environment: { PI_WEB_CONFIG: "/tmp/config.json" },
|
||||||
|
workingDirectory: "/checkout with space",
|
||||||
|
packageJsonPath: "/checkout with space/package.json",
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(plan).toMatchObject({
|
||||||
|
mode: "development",
|
||||||
|
backend: { kind: "launchd" },
|
||||||
|
shell: { name: "fish", executable: "/opt/homebrew/bin/fish" },
|
||||||
|
services: [
|
||||||
|
{
|
||||||
|
id: "sessiond",
|
||||||
|
shellCommand: "exec npm run start:sessiond",
|
||||||
|
strategy: { kind: "development-npm-script", script: "start:sessiond" },
|
||||||
|
restart: "never",
|
||||||
|
environment: { PI_WEB_CONFIG: "/tmp/config.json" },
|
||||||
|
workingDirectory: "/checkout with space",
|
||||||
|
prerequisites: [
|
||||||
|
{ id: "sessiond.node", kind: "node-version", minimumMajor: 22 },
|
||||||
|
{ id: "sessiond.command.npm", kind: "command-available", command: "npm" },
|
||||||
|
{ id: "sessiond.package-scripts", kind: "package-scripts", scripts: ["start:sessiond"] },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: "uiDev",
|
||||||
|
shellCommand: "exec /usr/bin/env bash -c 'trap \"kill 0\" EXIT; npm run dev:web & npm run dev:client & wait'",
|
||||||
|
strategy: { kind: "development-npm-script-group", scripts: ["dev:web", "dev:client"], interpreter: "bash" },
|
||||||
|
restart: "never",
|
||||||
|
workingDirectory: "/checkout with space",
|
||||||
|
after: ["sessiond"],
|
||||||
|
wants: ["sessiond"],
|
||||||
|
prerequisites: [
|
||||||
|
{ id: "uiDev.node", kind: "node-version", minimumMajor: 22 },
|
||||||
|
{ id: "uiDev.command.npm", kind: "command-available", command: "npm" },
|
||||||
|
{ id: "uiDev.command.bash", kind: "command-available", command: "bash" },
|
||||||
|
{ id: "uiDev.package-scripts", kind: "package-scripts", scripts: ["dev:web", "dev:client"] },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
});
|
||||||
|
|
||||||
|
const serviceCommandRequirements = plan.services.flatMap((service) => service.prerequisites)
|
||||||
|
.filter((prerequisite) => prerequisite.kind === "command-available")
|
||||||
|
.map((prerequisite) => prerequisite.command);
|
||||||
|
expect(serviceCommandRequirements).toEqual(["npm", "npm", "bash"]);
|
||||||
|
expect(serviceCommandRequirements).not.toContain("pi-web-server");
|
||||||
|
expect(serviceCommandRequirements).not.toContain("pi-web-sessiond");
|
||||||
|
|
||||||
|
expect(planValidationProbeRequests(plan)).toMatchObject([
|
||||||
|
{ backend: { kind: "launchd" }, workingDirectory: "/checkout with space" },
|
||||||
|
{ backend: { kind: "launchd" }, workingDirectory: "/checkout with space" },
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,540 @@
|
|||||||
|
export type NativeServiceBackendKind = "systemd" | "launchd";
|
||||||
|
export type NativeServiceMode = "production" | "development";
|
||||||
|
export type NativeServiceId = "sessiond" | "web" | "uiDev";
|
||||||
|
export type ProductionNativeServiceId = Extract<NativeServiceId, "sessiond" | "web">;
|
||||||
|
export type NativeServiceShellName = "bash" | "zsh" | "fish";
|
||||||
|
export type NativeServiceRestartPolicy = "on-failure" | "never";
|
||||||
|
|
||||||
|
export interface NativeServiceBackend {
|
||||||
|
kind: NativeServiceBackendKind;
|
||||||
|
label: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface NativeServiceShell {
|
||||||
|
name: NativeServiceShellName;
|
||||||
|
executable: string;
|
||||||
|
source: "detected" | "fallback";
|
||||||
|
detectedExecutable: string | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface NativeServiceManagerRef {
|
||||||
|
systemdName: string;
|
||||||
|
launchdLabel: string;
|
||||||
|
launchdPlistName: string;
|
||||||
|
logName: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
export type NativeServiceCommandStrategy =
|
||||||
|
| {
|
||||||
|
kind: "configured-override";
|
||||||
|
command: string;
|
||||||
|
verification: "unverified";
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "named-command";
|
||||||
|
command: string;
|
||||||
|
selectedBy: "authoritative-backend-probe";
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "bundled-entrypoint";
|
||||||
|
command: "node";
|
||||||
|
entrypointPath: string;
|
||||||
|
namedCommand: string;
|
||||||
|
namedCommandFailure: string | null;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "development-npm-script";
|
||||||
|
script: string;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "development-npm-script-group";
|
||||||
|
scripts: readonly string[];
|
||||||
|
interpreter: "bash";
|
||||||
|
};
|
||||||
|
|
||||||
|
export type NativeServicePrerequisite =
|
||||||
|
| {
|
||||||
|
id: string;
|
||||||
|
kind: "command-available";
|
||||||
|
command: string;
|
||||||
|
description: string;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
id: string;
|
||||||
|
kind: "node-version";
|
||||||
|
command: "node";
|
||||||
|
minimumMajor: number;
|
||||||
|
description: string;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
id: string;
|
||||||
|
kind: "readable-file";
|
||||||
|
path: string;
|
||||||
|
description: string;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
id: string;
|
||||||
|
kind: "package-scripts";
|
||||||
|
packageJsonPath: string;
|
||||||
|
scripts: readonly string[];
|
||||||
|
description: string;
|
||||||
|
};
|
||||||
|
|
||||||
|
export interface NativeServicePlanService {
|
||||||
|
id: NativeServiceId;
|
||||||
|
manager: NativeServiceManagerRef;
|
||||||
|
description: string;
|
||||||
|
shellCommand: string;
|
||||||
|
strategy: NativeServiceCommandStrategy;
|
||||||
|
restart: NativeServiceRestartPolicy;
|
||||||
|
environment: Readonly<Record<string, string>>;
|
||||||
|
workingDirectory: string | null;
|
||||||
|
after: readonly NativeServiceId[];
|
||||||
|
wants: readonly NativeServiceId[];
|
||||||
|
prerequisites: readonly NativeServicePrerequisite[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface NativeServicePlan {
|
||||||
|
mode: NativeServiceMode;
|
||||||
|
backend: NativeServiceBackend;
|
||||||
|
shell: NativeServiceShell;
|
||||||
|
services: readonly NativeServicePlanService[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface NativeServiceProbeRequest {
|
||||||
|
purpose: "executable-selection" | "plan-validation";
|
||||||
|
backend: NativeServiceBackend;
|
||||||
|
shell: NativeServiceShell;
|
||||||
|
environment: Readonly<Record<string, string>>;
|
||||||
|
workingDirectory: string | null;
|
||||||
|
prerequisites: readonly NativeServicePrerequisite[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface NativeServicePrerequisiteOutcome {
|
||||||
|
prerequisiteId: string;
|
||||||
|
status: "satisfied" | "unsatisfied";
|
||||||
|
detail: string | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export type NativeServiceProbeResult =
|
||||||
|
| {
|
||||||
|
kind: "completed";
|
||||||
|
outcomes: readonly NativeServicePrerequisiteOutcome[];
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "infrastructure-failure";
|
||||||
|
message: string;
|
||||||
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Runs requirements in the real native service-manager context represented by
|
||||||
|
* the request. Implementations must not treat the caller shell or a simulated
|
||||||
|
* `env -i` environment as authoritative. Timeouts, manager failures, malformed
|
||||||
|
* output, and cleanup failures are infrastructure failures; a missing command
|
||||||
|
* is a completed probe with an unsatisfied outcome.
|
||||||
|
*/
|
||||||
|
export interface NativeServiceAuthoritativeProbe {
|
||||||
|
run(request: NativeServiceProbeRequest): Promise<NativeServiceProbeResult>;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ProductionNativeServiceExecutableInput {
|
||||||
|
configuredCommand: string | undefined;
|
||||||
|
namedCommand: string;
|
||||||
|
bundledEntrypointPath: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ProductionNativeServicePlanInput {
|
||||||
|
backend: NativeServiceBackend;
|
||||||
|
shell: NativeServiceShell;
|
||||||
|
environment: Readonly<Record<string, string>>;
|
||||||
|
executables: Readonly<Record<ProductionNativeServiceId, ProductionNativeServiceExecutableInput>>;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface DevelopmentNativeServicePlanInput {
|
||||||
|
backend: NativeServiceBackend;
|
||||||
|
shell: NativeServiceShell;
|
||||||
|
environment: Readonly<Record<string, string>>;
|
||||||
|
workingDirectory: string;
|
||||||
|
packageJsonPath: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface NativeServicePlanDependencies {
|
||||||
|
probe: NativeServiceAuthoritativeProbe;
|
||||||
|
fileExists(path: string): boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
export type NativeServicePlanFailure =
|
||||||
|
| {
|
||||||
|
kind: "probe-infrastructure";
|
||||||
|
serviceIds: readonly ProductionNativeServiceId[];
|
||||||
|
message: string;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "entrypoint-inspection-failure";
|
||||||
|
serviceId: ProductionNativeServiceId;
|
||||||
|
entrypointPath: string;
|
||||||
|
message: string;
|
||||||
|
}
|
||||||
|
| {
|
||||||
|
kind: "executable-unavailable";
|
||||||
|
serviceId: ProductionNativeServiceId;
|
||||||
|
namedCommand: string;
|
||||||
|
namedCommandFailure: string | null;
|
||||||
|
bundledEntrypointPath: string;
|
||||||
|
};
|
||||||
|
|
||||||
|
export type NativeServicePlanResolution =
|
||||||
|
| { ok: true; plan: NativeServicePlan }
|
||||||
|
| { ok: false; failures: readonly NativeServicePlanFailure[] };
|
||||||
|
|
||||||
|
const nativeServiceRefs: Readonly<Record<NativeServiceId, NativeServiceManagerRef>> = {
|
||||||
|
sessiond: {
|
||||||
|
systemdName: "pi-web-sessiond.service",
|
||||||
|
launchdLabel: "com.pi-web.sessiond",
|
||||||
|
launchdPlistName: "com.pi-web.sessiond.plist",
|
||||||
|
logName: "sessiond.log",
|
||||||
|
},
|
||||||
|
web: {
|
||||||
|
systemdName: "pi-web.service",
|
||||||
|
launchdLabel: "com.pi-web.web",
|
||||||
|
launchdPlistName: "com.pi-web.web.plist",
|
||||||
|
logName: "web.log",
|
||||||
|
},
|
||||||
|
uiDev: {
|
||||||
|
systemdName: "pi-web-ui-dev.service",
|
||||||
|
launchdLabel: "com.pi-web.ui-dev",
|
||||||
|
launchdPlistName: "com.pi-web.ui-dev.plist",
|
||||||
|
logName: "ui-dev.log",
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const productionServiceIds = ["sessiond", "web"] as const satisfies readonly ProductionNativeServiceId[];
|
||||||
|
|
||||||
|
export async function resolveProductionNativeServicePlan(
|
||||||
|
input: ProductionNativeServicePlanInput,
|
||||||
|
dependencies: NativeServicePlanDependencies,
|
||||||
|
): Promise<NativeServicePlanResolution> {
|
||||||
|
const configuredStrategies = new Map<ProductionNativeServiceId, NativeServiceCommandStrategy>();
|
||||||
|
const selectionRequirements: NativeServicePrerequisite[] = [];
|
||||||
|
const serviceIdsToProbe: ProductionNativeServiceId[] = [];
|
||||||
|
|
||||||
|
for (const serviceId of productionServiceIds) {
|
||||||
|
const executable = input.executables[serviceId];
|
||||||
|
if (hasConfiguredCommand(executable.configuredCommand)) {
|
||||||
|
configuredStrategies.set(serviceId, {
|
||||||
|
kind: "configured-override",
|
||||||
|
command: executable.configuredCommand,
|
||||||
|
verification: "unverified",
|
||||||
|
});
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
serviceIdsToProbe.push(serviceId);
|
||||||
|
selectionRequirements.push(commandRequirement(serviceId, executable.namedCommand));
|
||||||
|
}
|
||||||
|
|
||||||
|
let outcomes = new Map<string, NativeServicePrerequisiteOutcome>();
|
||||||
|
if (selectionRequirements.length > 0) {
|
||||||
|
const probeResult = await runSelectionProbe(input, selectionRequirements, dependencies.probe);
|
||||||
|
if (probeResult.kind === "infrastructure-failure") {
|
||||||
|
return {
|
||||||
|
ok: false,
|
||||||
|
failures: [{ kind: "probe-infrastructure", serviceIds: serviceIdsToProbe, message: probeResult.message }],
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
const parsedOutcomes = probeOutcomes(selectionRequirements, probeResult.outcomes);
|
||||||
|
if (parsedOutcomes.kind === "infrastructure-failure") {
|
||||||
|
return {
|
||||||
|
ok: false,
|
||||||
|
failures: [{ kind: "probe-infrastructure", serviceIds: serviceIdsToProbe, message: parsedOutcomes.message }],
|
||||||
|
};
|
||||||
|
}
|
||||||
|
outcomes = parsedOutcomes.outcomes;
|
||||||
|
}
|
||||||
|
|
||||||
|
const strategies = new Map(configuredStrategies);
|
||||||
|
const failures: NativeServicePlanFailure[] = [];
|
||||||
|
|
||||||
|
for (const serviceId of serviceIdsToProbe) {
|
||||||
|
const executable = input.executables[serviceId];
|
||||||
|
const outcome = outcomes.get(commandRequirementId(serviceId, executable.namedCommand));
|
||||||
|
if (outcome?.status === "satisfied") {
|
||||||
|
strategies.set(serviceId, {
|
||||||
|
kind: "named-command",
|
||||||
|
command: executable.namedCommand,
|
||||||
|
selectedBy: "authoritative-backend-probe",
|
||||||
|
});
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
let entrypointExists: boolean;
|
||||||
|
try {
|
||||||
|
entrypointExists = dependencies.fileExists(executable.bundledEntrypointPath);
|
||||||
|
} catch (error: unknown) {
|
||||||
|
failures.push({
|
||||||
|
kind: "entrypoint-inspection-failure",
|
||||||
|
serviceId,
|
||||||
|
entrypointPath: executable.bundledEntrypointPath,
|
||||||
|
message: errorMessage(error),
|
||||||
|
});
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (entrypointExists) {
|
||||||
|
strategies.set(serviceId, {
|
||||||
|
kind: "bundled-entrypoint",
|
||||||
|
command: "node",
|
||||||
|
entrypointPath: executable.bundledEntrypointPath,
|
||||||
|
namedCommand: executable.namedCommand,
|
||||||
|
namedCommandFailure: outcome?.detail ?? null,
|
||||||
|
});
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
failures.push({
|
||||||
|
kind: "executable-unavailable",
|
||||||
|
serviceId,
|
||||||
|
namedCommand: executable.namedCommand,
|
||||||
|
namedCommandFailure: outcome?.detail ?? null,
|
||||||
|
bundledEntrypointPath: executable.bundledEntrypointPath,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
if (failures.length > 0) return { ok: false, failures };
|
||||||
|
|
||||||
|
return {
|
||||||
|
ok: true,
|
||||||
|
plan: {
|
||||||
|
mode: "production",
|
||||||
|
backend: input.backend,
|
||||||
|
shell: input.shell,
|
||||||
|
services: productionServiceIds.map((serviceId) => productionService(input, serviceId, requiredStrategy(strategies, serviceId))),
|
||||||
|
},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
export function createDevelopmentNativeServicePlan(input: DevelopmentNativeServicePlanInput): NativeServicePlan {
|
||||||
|
const environment = copyEnvironment(input.environment);
|
||||||
|
const sessiondScripts = ["start:sessiond"] as const;
|
||||||
|
const uiDevScripts = ["dev:web", "dev:client"] as const;
|
||||||
|
const uiDevCommand = 'trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait';
|
||||||
|
|
||||||
|
return {
|
||||||
|
mode: "development",
|
||||||
|
backend: input.backend,
|
||||||
|
shell: input.shell,
|
||||||
|
services: [
|
||||||
|
{
|
||||||
|
id: "sessiond",
|
||||||
|
manager: nativeServiceRefs.sessiond,
|
||||||
|
description: "PI WEB session daemon (dev)",
|
||||||
|
shellCommand: "exec npm run start:sessiond",
|
||||||
|
strategy: { kind: "development-npm-script", script: "start:sessiond" },
|
||||||
|
restart: "never",
|
||||||
|
environment,
|
||||||
|
workingDirectory: input.workingDirectory,
|
||||||
|
after: [],
|
||||||
|
wants: [],
|
||||||
|
prerequisites: [
|
||||||
|
nodeRequirement("sessiond"),
|
||||||
|
commandRequirement("sessiond", "npm"),
|
||||||
|
packageScriptsRequirement("sessiond", input.packageJsonPath, sessiondScripts),
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: "uiDev",
|
||||||
|
manager: nativeServiceRefs.uiDev,
|
||||||
|
description: "PI WEB UI dev server",
|
||||||
|
shellCommand: `exec /usr/bin/env bash -c ${shellSingleQuote(input.shell.name, uiDevCommand)}`,
|
||||||
|
strategy: { kind: "development-npm-script-group", scripts: uiDevScripts, interpreter: "bash" },
|
||||||
|
restart: "never",
|
||||||
|
environment,
|
||||||
|
workingDirectory: input.workingDirectory,
|
||||||
|
after: ["sessiond"],
|
||||||
|
wants: ["sessiond"],
|
||||||
|
prerequisites: [
|
||||||
|
nodeRequirement("uiDev"),
|
||||||
|
commandRequirement("uiDev", "npm"),
|
||||||
|
commandRequirement("uiDev", "bash"),
|
||||||
|
packageScriptsRequirement("uiDev", input.packageJsonPath, uiDevScripts),
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
export function planValidationProbeRequests(plan: NativeServicePlan): readonly NativeServiceProbeRequest[] {
|
||||||
|
return plan.services.flatMap((service) => service.prerequisites.length === 0 ? [] : [{
|
||||||
|
purpose: "plan-validation" as const,
|
||||||
|
backend: plan.backend,
|
||||||
|
shell: plan.shell,
|
||||||
|
environment: service.environment,
|
||||||
|
workingDirectory: service.workingDirectory,
|
||||||
|
prerequisites: service.prerequisites,
|
||||||
|
}]);
|
||||||
|
}
|
||||||
|
|
||||||
|
function productionService(
|
||||||
|
input: ProductionNativeServicePlanInput,
|
||||||
|
serviceId: ProductionNativeServiceId,
|
||||||
|
strategy: NativeServiceCommandStrategy,
|
||||||
|
): NativeServicePlanService {
|
||||||
|
const isWeb = serviceId === "web";
|
||||||
|
return {
|
||||||
|
id: serviceId,
|
||||||
|
manager: nativeServiceRefs[serviceId],
|
||||||
|
description: isWeb ? "PI WEB server" : "PI WEB session daemon",
|
||||||
|
shellCommand: `exec ${strategyCommand(input.shell, strategy)}`,
|
||||||
|
strategy,
|
||||||
|
restart: "on-failure",
|
||||||
|
environment: copyEnvironment(input.environment),
|
||||||
|
workingDirectory: null,
|
||||||
|
after: isWeb ? ["sessiond"] : [],
|
||||||
|
wants: isWeb ? ["sessiond"] : [],
|
||||||
|
prerequisites: strategyPrerequisites(serviceId, strategy),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function strategyCommand(shell: NativeServiceShell, strategy: NativeServiceCommandStrategy): string {
|
||||||
|
switch (strategy.kind) {
|
||||||
|
case "configured-override":
|
||||||
|
case "named-command":
|
||||||
|
return strategy.command;
|
||||||
|
case "bundled-entrypoint":
|
||||||
|
return `${strategy.command} ${shellSingleQuote(shell.name, strategy.entrypointPath)}`;
|
||||||
|
case "development-npm-script":
|
||||||
|
return `npm run ${strategy.script}`;
|
||||||
|
case "development-npm-script-group":
|
||||||
|
throw new Error("Development script groups define their complete service shell command");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function strategyPrerequisites(serviceId: ProductionNativeServiceId, strategy: NativeServiceCommandStrategy): readonly NativeServicePrerequisite[] {
|
||||||
|
switch (strategy.kind) {
|
||||||
|
case "configured-override":
|
||||||
|
return [];
|
||||||
|
case "named-command":
|
||||||
|
return [commandRequirement(serviceId, strategy.command), nodeRequirement(serviceId)];
|
||||||
|
case "bundled-entrypoint":
|
||||||
|
return [nodeRequirement(serviceId), readableFileRequirement(serviceId, strategy.entrypointPath)];
|
||||||
|
case "development-npm-script":
|
||||||
|
case "development-npm-script-group":
|
||||||
|
throw new Error(`Unexpected ${strategy.kind} strategy in a production plan`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function runSelectionProbe(
|
||||||
|
input: ProductionNativeServicePlanInput,
|
||||||
|
prerequisites: readonly NativeServicePrerequisite[],
|
||||||
|
probe: NativeServiceAuthoritativeProbe,
|
||||||
|
): Promise<NativeServiceProbeResult> {
|
||||||
|
try {
|
||||||
|
return await probe.run({
|
||||||
|
purpose: "executable-selection",
|
||||||
|
backend: input.backend,
|
||||||
|
shell: input.shell,
|
||||||
|
environment: copyEnvironment(input.environment),
|
||||||
|
workingDirectory: null,
|
||||||
|
prerequisites,
|
||||||
|
});
|
||||||
|
} catch (error: unknown) {
|
||||||
|
return { kind: "infrastructure-failure", message: errorMessage(error) };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function probeOutcomes(
|
||||||
|
prerequisites: readonly NativeServicePrerequisite[],
|
||||||
|
outcomes: readonly NativeServicePrerequisiteOutcome[],
|
||||||
|
): { kind: "completed"; outcomes: Map<string, NativeServicePrerequisiteOutcome> } | { kind: "infrastructure-failure"; message: string } {
|
||||||
|
const expectedIds = new Set(prerequisites.map((prerequisite) => prerequisite.id));
|
||||||
|
const byId = new Map<string, NativeServicePrerequisiteOutcome>();
|
||||||
|
|
||||||
|
for (const outcome of outcomes) {
|
||||||
|
if (!expectedIds.has(outcome.prerequisiteId)) {
|
||||||
|
return { kind: "infrastructure-failure", message: `Authoritative probe returned unexpected outcome ${outcome.prerequisiteId}.` };
|
||||||
|
}
|
||||||
|
if (byId.has(outcome.prerequisiteId)) {
|
||||||
|
return { kind: "infrastructure-failure", message: `Authoritative probe returned duplicate outcome ${outcome.prerequisiteId}.` };
|
||||||
|
}
|
||||||
|
byId.set(outcome.prerequisiteId, outcome);
|
||||||
|
}
|
||||||
|
|
||||||
|
const missing = prerequisites.find((prerequisite) => !byId.has(prerequisite.id));
|
||||||
|
if (missing !== undefined) {
|
||||||
|
return { kind: "infrastructure-failure", message: `Authoritative probe returned no outcome for ${missing.id}.` };
|
||||||
|
}
|
||||||
|
return { kind: "completed", outcomes: byId };
|
||||||
|
}
|
||||||
|
|
||||||
|
function requiredStrategy(
|
||||||
|
strategies: ReadonlyMap<ProductionNativeServiceId, NativeServiceCommandStrategy>,
|
||||||
|
serviceId: ProductionNativeServiceId,
|
||||||
|
): NativeServiceCommandStrategy {
|
||||||
|
const strategy = strategies.get(serviceId);
|
||||||
|
if (strategy === undefined) throw new Error(`Missing executable strategy for ${serviceId}`);
|
||||||
|
return strategy;
|
||||||
|
}
|
||||||
|
|
||||||
|
function hasConfiguredCommand(command: string | undefined): command is string {
|
||||||
|
return command !== undefined && command.trim() !== "";
|
||||||
|
}
|
||||||
|
|
||||||
|
function commandRequirementId(serviceId: NativeServiceId, command: string): string {
|
||||||
|
return `${serviceId}.command.${command}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function commandRequirement(serviceId: NativeServiceId, command: string): NativeServicePrerequisite {
|
||||||
|
return {
|
||||||
|
id: commandRequirementId(serviceId, command),
|
||||||
|
kind: "command-available",
|
||||||
|
command,
|
||||||
|
description: `${command} is available to the service shell`,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function nodeRequirement(serviceId: NativeServiceId): NativeServicePrerequisite {
|
||||||
|
return {
|
||||||
|
id: `${serviceId}.node`,
|
||||||
|
kind: "node-version",
|
||||||
|
command: "node",
|
||||||
|
minimumMajor: 22,
|
||||||
|
description: "node >= 22 is available to the service shell",
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function readableFileRequirement(serviceId: NativeServiceId, path: string): NativeServicePrerequisite {
|
||||||
|
return {
|
||||||
|
id: `${serviceId}.entrypoint`,
|
||||||
|
kind: "readable-file",
|
||||||
|
path,
|
||||||
|
description: `bundled entrypoint is readable: ${path}`,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function packageScriptsRequirement(
|
||||||
|
serviceId: NativeServiceId,
|
||||||
|
packageJsonPath: string,
|
||||||
|
scripts: readonly string[],
|
||||||
|
): NativeServicePrerequisite {
|
||||||
|
return {
|
||||||
|
id: `${serviceId}.package-scripts`,
|
||||||
|
kind: "package-scripts",
|
||||||
|
packageJsonPath,
|
||||||
|
scripts,
|
||||||
|
description: `package.json defines scripts: ${scripts.join(", ")}`,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function shellSingleQuote(shell: NativeServiceShellName, value: string): string {
|
||||||
|
if (shell === "fish") return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
|
||||||
|
return `'${value.replaceAll("'", "'\\''")}'`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function copyEnvironment(environment: Readonly<Record<string, string>>): Readonly<Record<string, string>> {
|
||||||
|
return { ...environment };
|
||||||
|
}
|
||||||
|
|
||||||
|
function errorMessage(error: unknown): string {
|
||||||
|
return error instanceof Error ? error.message : String(error);
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user