Python
/** Shared, fail-closed discovery for a standalone One Memory Runtime. */
import { lstat, readFile } from "node:fs/promises";
import path from "node:path";
import type { HealthResponse } from "@one-memory/contracts";
export type RuntimeIdentity = HealthResponse;
export interface RuntimeAttachment {
instanceId: string;
apiToken: string;
host: "127.0.0.1";
port: number;
servicePid: number | null;
/** Sidecar (Broker) state published by the outer Runtime's receipt. `failed`
* means the Runtime is alive but a capability is gone -> callers report
* `degraded`, never `healthy`. Null/absent when the receipt predates the
* field (an older Runtime), which is treated as "unknown", not "healthy". */
sidecarState?: "running" | "failed" | "stopped" | null;
health: RuntimeIdentity;
}
export interface RuntimeAttachmentOptions {
dataDir: string;
processIsAlive(pid: number): boolean;
probeIdentity(port: number, apiToken: string): Promise<RuntimeIdentity>;
platform?: NodeJS.Platform;
currentUid?: number;
requireServiceReceipt?: boolean;
}
export class RuntimeDiscoveryError extends Error {
readonly code:
| "runtime_receipt_invalid"
| "runtime_receipt_unavailable"
| "runtime_service_receipt_invalid"
| "runtime_service_receipt_unavailable"
| "runtime_service_not_ready"
| "runtime_token_unavailable"
| "runtime_identity_unavailable"
| "runtime_identity_mismatch";
constructor(code: RuntimeDiscoveryError["code"], options?: ErrorOptions) {
super(code, options);
this.name = "RuntimeDiscoveryError";
this.code = code;
}
}
interface RuntimeReceipt {
schemaVersion?: number;
service?: string;
instanceId?: string;
pid: number;
parentPid: number | null;
host?: string;
port?: number;
startedAt: string;
}
interface RuntimeServiceReceipt {
instanceId: string;
pid: number;
status: "starting" | "running" | "stopping";
corePort: number | null;
sidecarState: "running" | "failed" | "stopped" | null;
}
/** The Core port a *running* managed Runtime published, or null when there is
* no usable receipt.
*
* `runtime-service.json.core_port` is the one authority for which port the
* Core actually bound — it is written after the bind succeeds, from the URL the
* Runtime itself reached. Callers that would otherwise guess (the desktop
* bridge, the renderer's base URL) read this instead of assuming a fixed 8765,
* so a non-default install root cannot be pointed at the daily Core.
*/
export async function readPublishedCorePort(
dataDir: string,
): Promise<number | null> {
const receipt = await readRuntimeServiceReceipt(dataDir).catch(() => null);
if (receipt === null || receipt.status !== "running") return null;
return receipt.corePort;
}
/**
* Return a verified standalone Runtime, or null when no attachable standalone
* instance is present. A live v1 instance that cannot be authenticated throws:
* callers must not race it with another writer.
*/
export async function discoverRuntimeAttachment(
options: RuntimeAttachmentOptions,
): Promise<RuntimeAttachment | null> {
const receipt = await readRuntimeReceipt(options.dataDir);
if (receipt === null || !options.processIsAlive(receipt.pid)) return null;
// A parent-owned Core is another desktop's child or a recoverable orphan,
// not the standalone Runtime this contract is allowed to attach to.
let service: RuntimeServiceReceipt | null = null;
if (receipt.parentPid !== null || options.requireServiceReceipt) {
service = await readRuntimeServiceReceipt(options.dataDir);
if (service === null) {
// A live Core is not evidence that another Runtime may safely be started.
// The launcher may wait for this receipt only after its own spawn.
if (options.requireServiceReceipt) {
throw new RuntimeDiscoveryError("runtime_service_not_ready");
}
return null;
}
if (
!options.processIsAlive(service.pid) ||
(receipt.parentPid !== null && service.pid !== receipt.parentPid) ||
service.instanceId !== receipt.instanceId
) {
throw new RuntimeDiscoveryError("runtime_service_receipt_invalid");
}
if (service.status !== "running" || service.corePort !== receipt.port) {
throw new RuntimeDiscoveryError("runtime_service_not_ready");
}
}
// Legacy receipts stay on the caller's existing ownership/conflict path.
if (receipt.schemaVersion !== 1 && receipt.service === undefined) return null;
if (!isAttachableReceipt(receipt)) {
throw new RuntimeDiscoveryError("runtime_receipt_invalid");
}
const token = await readRuntimeToken(options);
if (token === null) {
throw new RuntimeDiscoveryError("runtime_token_unavailable");
}
let health: RuntimeIdentity;
try {
health = await options.probeIdentity(receipt.port, token);
} catch (error) {
throw new RuntimeDiscoveryError("runtime_identity_unavailable", {
cause: error,
});
}
if (!isRuntimeIdentity(health, receipt.instanceId)) {
throw new RuntimeDiscoveryError("runtime_identity_mismatch");
}
return Object.freeze({
instanceId: receipt.instanceId,
apiToken: token,
host: "127.0.0.1",
port: receipt.port,
servicePid: service?.pid ?? null,
sidecarState: service?.sidecarState ?? null,
health: Object.freeze({ ...health }),
});
}
async function readRuntimeServiceReceipt(
dataDir: string,
): Promise<RuntimeServiceReceipt | null> {
let raw: string;
try {
raw = await readFile(path.join(dataDir, "runtime-service.json"), "utf8");
} catch (error) {
if (isMissingFile(error)) return null;
throw new RuntimeDiscoveryError("runtime_service_receipt_unavailable");
}
let value: unknown;
try {
value = JSON.parse(raw);
} catch {
throw new RuntimeDiscoveryError("runtime_service_receipt_invalid");
}
if (!value || typeof value !== "object") {
throw new RuntimeDiscoveryError("runtime_service_receipt_invalid");
}
// Unknown keys are ignored: a receipt written by an older Runtime may still
// carry `reader_port`, which no longer means anything.
const item = value as Record<string, unknown>;
if (
item.schema_version !== 1 ||
item.service !== "one-memory-runtime" ||
!["starting", "running", "stopping"].includes(String(item.status)) ||
typeof item.instance_id !== "string" ||
!item.instance_id ||
typeof item.pid !== "number" ||
!Number.isInteger(item.pid) ||
item.pid <= 1 ||
(item.core_port !== null &&
(typeof item.core_port !== "number" ||
!Number.isInteger(item.core_port) ||
item.core_port < 1024 ||
item.core_port > 65_535)) ||
(item.sidecar !== undefined &&
item.sidecar !== "running" &&
item.sidecar !== "failed" &&
item.sidecar !== "stopped")
) {
throw new RuntimeDiscoveryError("runtime_service_receipt_invalid");
}
return {
instanceId: item.instance_id,
pid: item.pid,
status: item.status as RuntimeServiceReceipt["status"],
corePort: item.core_port,
sidecarState:
item.sidecar === undefined
? null
: (item.sidecar as RuntimeServiceReceipt["sidecarState"]),
};
}
async function readRuntimeReceipt(
dataDir: string,
): Promise<RuntimeReceipt | null> {
let raw: string;
try {
raw = await readFile(path.join(dataDir, "runtime.json"), "utf8");
} catch (error) {
if (isMissingFile(error)) return null;
throw new RuntimeDiscoveryError("runtime_receipt_unavailable");
}
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
throw new RuntimeDiscoveryError("runtime_receipt_invalid");
}
if (typeof parsed !== "object" || parsed === null) {
throw new RuntimeDiscoveryError("runtime_receipt_invalid");
}
const value = parsed as Record<string, unknown>;
if (typeof value.pid !== "number" || !Number.isInteger(value.pid)) {
throw new RuntimeDiscoveryError("runtime_receipt_invalid");
}
return {
schemaVersion:
typeof value.schema_version === "number"
? value.schema_version
: undefined,
service: typeof value.service === "string" ? value.service : undefined,
instanceId:
typeof value.instance_id === "string" ? value.instance_id : undefined,
pid: value.pid,
parentPid: typeof value.parent_pid === "number" ? value.parent_pid : null,
host: typeof value.host === "string" ? value.host : undefined,
port: typeof value.port === "number" ? value.port : undefined,
startedAt:
typeof value.started_at === "string" ? value.started_at : "未知时间",
};
}
async function readRuntimeToken(
options: RuntimeAttachmentOptions,
): Promise<string | null> {
const platform = options.platform ?? process.platform;
if (platform === "win32") return null;
const target = path.join(options.dataDir, "runtime-token");
try {
const metadata = await lstat(target);
if (!metadata.isFile() || metadata.isSymbolicLink()) return null;
if ((metadata.mode & 0o077) !== 0) return null;
const currentUid =
options.currentUid ??
(typeof process.getuid === "function" ? process.getuid() : undefined);
if (currentUid !== undefined && metadata.uid !== currentUid) return null;
const token = await readFile(target, "utf8");
return token.length > 0 && token.length <= 4096 ? token : null;
} catch {
return null;
}
}
function isMissingFile(error: unknown): boolean {
return (
error !== null &&
typeof error === "object" &&
"code" in error &&
error.code === "ENOENT"
);
}
function isAttachableReceipt(
receipt: RuntimeReceipt,
): receipt is RuntimeReceipt & {
schemaVersion: 1;
service: "one-memory-core";
instanceId: string;
host: "127.0.0.1";
port: number;
} {
return (
receipt.schemaVersion === 1 &&
receipt.service === "one-memory-core" &&
typeof receipt.instanceId === "string" &&
receipt.instanceId.length > 0 &&
receipt.host === "127.0.0.1" &&
Number.isInteger(receipt.port) &&
(receipt.port ?? 0) >= 1024 &&
(receipt.port ?? 0) <= 65_535
);
}
function isRuntimeIdentity(
value: RuntimeIdentity,
instanceId: string,
): value is RuntimeIdentity {
return (
value?.status === "ok" &&
value.service === "one-memory-core" &&
typeof value.version === "string" &&
value.instance_id === instanceId
);
}