@cofy-x/axern-sdk 0.2.0-bootstrap.0

package/dist/sandbox/lifecycle.js

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SandboxTimeoutError, SandboxValidationError } from "../errors/index.js";
+export const defaultSandboxArgv = ["/bin/sh", "-lc", "sleep infinity"];
+export function validateSandboxOptions(options) {
+    const sourceCount = [options.templateId, options.image, options.environmentId].filter((source) => source !== undefined && source !== "").length;
+    if (sourceCount !== 1) {
+        throw new SandboxValidationError("exactly one of templateId, image, or environmentId is required");
+    }
+}
+export function sandboxLabels(labels) {
+    return {
+        "axern.sdk": "typescript",
+        ...(labels ?? {}),
+    };
+}
+export function sandboxMetadata(options, state) {
+    return {
+        ...state,
+        namespace: options.namespace ?? "default",
+        runtimeClass: options.runtimeClass ?? "",
+        labels: sandboxLabels(options.labels),
+        source: sandboxSource(options),
+    };
+}
+export async function waitReadyReplica(serviceId, timeoutMs, listReplicas) {
+    const deadline = Date.now() + timeoutMs;
+    let lastReplicas = [];
+    while (Date.now() < deadline) {
+        lastReplicas = await listReplicas(serviceId);
+        const candidate = lastReplicas.find((replica) => replica.ready === true &&
+            replica.ended !== true &&
+            replica.outdated !== true &&
+            Number(replica.status ?? 0) === 4);
+        if (candidate !== undefined) {
+            return candidate;
+        }
+        await sleep(2_000);
+    }
+    const details = lastReplicas.map((replica) => `${String(replica.id ?? "")}:${String(replica.status ?? "")}`).join(", ");
+    throw new SandboxTimeoutError(`service ${serviceId} did not produce a ready sandbox replica: ${details}`);
+}
+function sandboxSource(options) {
+    if (options.templateId !== undefined && options.templateId !== "") {
+        return "template";
+    }
+    if (options.image !== undefined && options.image !== "") {
+        return "image";
+    }
+    return "environment";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/tunnel/connector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TunnelConnectorOptions } from "../types.js";
+import type { GatewayTransportOptions } from "./relay.js";
+import type { TunnelSession } from "./types.js";
+export interface TunnelConnectorConfig {
+    session: TunnelSession;
+    clientToken: string;
+    upstream: string;
+    transport?: GatewayTransportOptions;
+    connector?: TunnelConnectorOptions;
+}
+export declare class TunnelConnector {
+    private readonly config;
+    private stopped;
+    private activeCall?;
+    private activeClient?;
+    private activeSession?;
+    private reconnecting;
+    private relayTarget;
+    private upstreamTarget?;
+    constructor(config: TunnelConnectorConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private connectOnce;
+    private handleRelayClosed;
+    private reconnectLoop;
+    private heartbeat;
+    private closeActiveRelay;
+    private requiredUpstreamTarget;
+}

package/dist/tunnel/connector.js

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { serviceConstructor } from "../generated/proto.js";
+import { debugFrame } from "./debug.js";
+import { isTerminalRelayError, relayChannelOptions, relayCredentials } from "./relay.js";
+import { TunnelRelaySession } from "./session.js";
+import { parseTcpTarget } from "./target.js";
+const defaultPingIntervalMs = 15_000;
+const defaultDialTimeoutMs = 5_000;
+const defaultMaxStreams = 128;
+const initialReconnectBackoffMs = 1_000;
+const maxReconnectBackoffMs = 10_000;
+export class TunnelConnector {
+    config;
+    stopped = false;
+    activeCall;
+    activeClient;
+    activeSession;
+    reconnecting = false;
+    relayTarget = "";
+    upstreamTarget;
+    constructor(config) {
+        this.config = config;
+    }
+    async start() {
+        const target = this.config.session.client_edge_target || this.config.session.edge_target;
+        if (target === undefined || target === "") {
+            throw new Error(`tunnel session ${this.config.session.session_id ?? ""} has no relay target`);
+        }
+        this.upstreamTarget = parseTcpTarget(this.config.upstream);
+        this.relayTarget = target;
+        this.heartbeat();
+        await this.connectOnce();
+    }
+    async stop() {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        this.closeActiveRelay();
+    }
+    async connectOnce() {
+        const TunnelRelay = serviceConstructor(["axern", "tunnel", "v1", "TunnelRelay"]);
+        const client = new TunnelRelay(this.relayTarget, relayCredentials(this.config.transport), relayChannelOptions(this.config.transport));
+        const call = client
+            .ConnectPeer();
+        const session = new TunnelRelaySession(call, {
+            upstreamTarget: this.requiredUpstreamTarget(),
+            dialTimeoutMs: this.config.connector?.dialTimeoutMs ?? defaultDialTimeoutMs,
+            maxStreams: this.config.connector?.maxStreams ?? defaultMaxStreams,
+        });
+        this.activeClient = client;
+        this.activeCall = call;
+        this.activeSession = session;
+        call.on("data", (frame) => {
+            debugFrame("recv", frame);
+            session.handleFrame(frame);
+        });
+        call.on("error", (error) => this.handleRelayClosed(error));
+        call.on("end", () => this.handleRelayClosed());
+        session.send({
+            peer_open: {
+                session_id: this.config.session.session_id ?? "",
+                peer_kind: 1,
+                token: this.config.clientToken,
+            },
+        });
+    }
+    handleRelayClosed(error) {
+        if (this.stopped || this.reconnecting) {
+            return;
+        }
+        this.closeActiveRelay();
+        if (error !== undefined && isTerminalRelayError(error)) {
+            this.stopped = true;
+            return;
+        }
+        this.reconnecting = true;
+        void this.reconnectLoop();
+    }
+    async reconnectLoop() {
+        let backoffMs = initialReconnectBackoffMs;
+        while (!this.stopped) {
+            await sleep(backoffMs);
+            if (this.stopped) {
+                break;
+            }
+            try {
+                await this.connectOnce();
+                this.reconnecting = false;
+                return;
+            }
+            catch (error) {
+                if (isTerminalRelayError(error)) {
+                    this.stopped = true;
+                    break;
+                }
+            }
+            backoffMs = Math.min(maxReconnectBackoffMs, backoffMs * 2);
+        }
+        this.reconnecting = false;
+    }
+    heartbeat() {
+        const interval = this.config.connector?.pingIntervalMs ?? defaultPingIntervalMs;
+        if (interval <= 0) {
+            return;
+        }
+        const timer = setInterval(() => {
+            if (this.stopped) {
+                clearInterval(timer);
+                return;
+            }
+            this.activeSession?.send({ ping: { id: String(Date.now()) } });
+        }, interval);
+        timer.unref();
+    }
+    closeActiveRelay() {
+        const call = this.activeCall;
+        const client = this.activeClient;
+        const session = this.activeSession;
+        this.activeCall = undefined;
+        this.activeClient = undefined;
+        this.activeSession = undefined;
+        call?.removeAllListeners();
+        session?.closeAll();
+        call?.end();
+        client?.close();
+    }
+    requiredUpstreamTarget() {
+        if (this.upstreamTarget === undefined) {
+            throw new Error("tunnel upstream target is not initialized");
+        }
+        return this.upstreamTarget;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/tunnel/control.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type * as grpc from "@grpc/grpc-js";
+import type { CreateTunnelSessionResult, TunnelSession } from "./types.js";
+export declare class TunnelControlClient {
+    private readonly client;
+    constructor(client: grpc.Client);
+    createSession(options: {
+        allocationId: string;
+        upstream: string;
+        proxyPort: number;
+        ttlSeconds: number;
+        readyTimeoutMs: number;
+    }): Promise<CreateTunnelSessionResult>;
+    getSession(sessionId: string): Promise<TunnelSession>;
+    listEvents(sessionId: string, limit?: number): Promise<Record<string, unknown>[]>;
+    renewSession(sessionId: string, clientToken: string, ttlSeconds: number): Promise<TunnelSession>;
+    revokeSession(sessionId: string, reason?: string): Promise<void>;
+}

package/dist/tunnel/control.js

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError } from "../errors/index.js";
+import { unary } from "../generated/proto.js";
+import { required } from "../validation.js";
+export class TunnelControlClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async createSession(options) {
+        try {
+            const response = await unary(this.client, "CreateTunnelSession", {
+                allocation_id: required("allocationId", options.allocationId),
+                remote_port: options.proxyPort,
+                local_target: required("upstream", options.upstream),
+                ttl: duration(options.ttlSeconds * 1000),
+                wait_ready: true,
+                ready_timeout: duration(options.readyTimeoutMs),
+            });
+            if (response.session === undefined) {
+                throw new Error("create tunnel session returned no session");
+            }
+            return {
+                session: response.session,
+                clientToken: response.client_token ?? "",
+            };
+        }
+        catch (error) {
+            throw mapRpcError(error, "create tunnel session", options.allocationId);
+        }
+    }
+    async getSession(sessionId) {
+        try {
+            const response = await unary(this.client, "GetTunnelSession", { session_id: required("sessionId", sessionId) });
+            if (response.session === undefined) {
+                throw new Error("get tunnel session returned no session");
+            }
+            return response.session;
+        }
+        catch (error) {
+            throw mapRpcError(error, "get tunnel session");
+        }
+    }
+    async listEvents(sessionId, limit = 30) {
+        try {
+            const response = await unary(this.client, "ListTunnelSessionEvents", { session_id: required("sessionId", sessionId), limit });
+            return response.events ?? [];
+        }
+        catch (error) {
+            throw mapRpcError(error, "list tunnel session events");
+        }
+    }
+    async renewSession(sessionId, clientToken, ttlSeconds) {
+        try {
+            const response = await unary(this.client, "RenewTunnelSession", {
+                session_id: required("sessionId", sessionId),
+                client_token: clientToken,
+                ttl: duration(ttlSeconds * 1000),
+            });
+            if (response.session === undefined) {
+                throw new Error("renew tunnel session returned no session");
+            }
+            return response.session;
+        }
+        catch (error) {
+            throw mapRpcError(error, "renew tunnel session");
+        }
+    }
+    async revokeSession(sessionId, reason = "sdk close") {
+        try {
+            await unary(this.client, "RevokeTunnelSession", {
+                session_id: required("sessionId", sessionId),
+                reason,
+            });
+        }
+        catch (error) {
+            throw mapRpcError(error, "revoke tunnel session");
+        }
+    }
+}
+function duration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    return {
+        seconds,
+        nanos: Math.floor((ms - seconds * 1000) * 1_000_000),
+    };
+}

package/dist/tunnel/debug.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare function debugFrame(direction: string, frame: Record<string, unknown>): void;

package/dist/tunnel/debug.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function debugFrame(direction, frame) {
+    if (process.env.AXERN_TS_TUNNEL_DEBUG !== "1") {
+        return;
+    }
+    const summary = { ...frame };
+    if ("stream_data" in summary) {
+        const data = summary.stream_data;
+        summary.stream_data = {
+            ...data,
+            data: Buffer.from(data.data ?? []).length,
+        };
+    }
+    process.stderr.write(`[axern-ts-tunnel] ${direction} ${JSON.stringify(summary)}\n`);
+}

package/dist/tunnel/relay.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as grpc from "@grpc/grpc-js";
+export interface GatewayTransportOptions {
+    insecure?: boolean;
+    tlsCaCert?: string;
+    tlsCert?: string;
+    tlsKey?: string;
+    serverName?: string;
+    proxyMode?: "env" | "direct";
+}
+export declare function relayCredentials(options: GatewayTransportOptions | undefined): grpc.ChannelCredentials;
+export declare function relayChannelOptions(options: GatewayTransportOptions | undefined): grpc.ChannelOptions;
+export declare function isTerminalRelayError(error: unknown): boolean;

package/dist/tunnel/relay.js

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as grpc from "@grpc/grpc-js";
+import { readFileSync } from "node:fs";
+export function relayCredentials(options) {
+    if (options?.insecure === true) {
+        return grpc.credentials.createInsecure();
+    }
+    const rootCerts = options?.tlsCaCert === undefined || options.tlsCaCert === ""
+        ? undefined
+        : readFileSync(options.tlsCaCert);
+    const privateKey = options?.tlsKey === undefined || options.tlsKey === ""
+        ? undefined
+        : readFileSync(options.tlsKey);
+    const certChain = options?.tlsCert === undefined || options.tlsCert === ""
+        ? undefined
+        : readFileSync(options.tlsCert);
+    return grpc.credentials.createSsl(rootCerts, privateKey, certChain);
+}
+export function relayChannelOptions(options) {
+    const channelOptions = {};
+    if (options?.serverName !== undefined && options.serverName !== "") {
+        channelOptions["grpc.ssl_target_name_override"] = options.serverName;
+    }
+    if (options?.proxyMode === "direct") {
+        channelOptions["grpc.enable_http_proxy"] = 0;
+    }
+    return channelOptions;
+}
+export function isTerminalRelayError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return false;
+    }
+    const code = Number(error.code);
+    return code === grpc.status.PERMISSION_DENIED ||
+        code === grpc.status.UNAUTHENTICATED ||
+        code === grpc.status.NOT_FOUND;
+}

package/dist/tunnel/runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TunnelOptions, TunnelMetadata } from "../types.js";
+import type { TunnelConnectorConfig } from "./connector.js";
+import type { GatewayTransportOptions } from "./relay.js";
+import type { CreateTunnelSessionResult, TunnelRuntime, TunnelSession } from "./types.js";
+export interface TunnelConnectorRunner {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface TunnelControl {
+    createSession(options: {
+        allocationId: string;
+        upstream: string;
+        proxyPort: number;
+        ttlSeconds: number;
+        readyTimeoutMs: number;
+    }): Promise<CreateTunnelSessionResult>;
+    getSession(sessionId: string): Promise<TunnelSession>;
+    listEvents(sessionId: string, limit?: number): Promise<Record<string, unknown>[]>;
+    renewSession(sessionId: string, clientToken: string, ttlSeconds: number): Promise<TunnelSession>;
+    revokeSession(sessionId: string, reason?: string): Promise<void>;
+}
+export declare function startTunnelRuntime(options: {
+    control: TunnelControl;
+    allocationId: string;
+    tunnel: TunnelOptions;
+    transport: GatewayTransportOptions;
+    connectorFactory?: (config: TunnelConnectorConfig) => TunnelConnectorRunner;
+}): Promise<TunnelRuntime>;
+export declare function tunnelMetadata(runtime: TunnelRuntime | undefined): TunnelMetadata | undefined;

package/dist/tunnel/runtime.js

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SandboxValidationError } from "../errors/index.js";
+import { TunnelConnector } from "./connector.js";
+import { parseTcpTarget } from "./target.js";
+const defaultProxyPort = 8786;
+const defaultTtlSeconds = 300;
+const defaultReadyTimeoutMs = 30_000;
+export async function startTunnelRuntime(options) {
+    validateTunnelOptions(options.tunnel);
+    const ttlSeconds = options.tunnel.ttlSeconds ?? defaultTtlSeconds;
+    const proxyPort = options.tunnel.proxyPort ?? defaultProxyPort;
+    const result = await options.control.createSession({
+        allocationId: options.allocationId,
+        upstream: options.tunnel.upstream,
+        proxyPort,
+        ttlSeconds,
+        readyTimeoutMs: options.tunnel.readyTimeoutMs ?? defaultReadyTimeoutMs,
+    });
+    const sessionId = result.session.session_id ?? "";
+    if (sessionId === "") {
+        throw new Error("create tunnel session returned no session id");
+    }
+    if (result.clientToken === "") {
+        throw new Error(`tunnel session ${sessionId} returned no client token`);
+    }
+    const connectorConfig = {
+        session: result.session,
+        clientToken: result.clientToken,
+        upstream: options.tunnel.upstream,
+        transport: options.transport,
+        connector: options.tunnel.connector,
+    };
+    const connector = (options.connectorFactory ?? ((config) => new TunnelConnector(config)))(connectorConfig);
+    let timer;
+    try {
+        await connector.start();
+        await waitClientConnected(options.control, sessionId, options.tunnel.readyTimeoutMs ?? defaultReadyTimeoutMs);
+        const session = await options.control.getSession(sessionId);
+        const boundAddr = session.bound_addr ?? "";
+        if (boundAddr === "") {
+            throw new Error(`tunnel session ${sessionId} has no bound address`);
+        }
+        const renewEveryMs = options.tunnel.renewEveryMs ?? Math.max(30_000, Math.floor((ttlSeconds * 1000) / 2));
+        timer = setInterval(() => {
+            void options.control.renewSession(sessionId, result.clientToken, ttlSeconds).catch(() => undefined);
+        }, renewEveryMs);
+        timer.unref();
+        return {
+            sessionId,
+            clientToken: result.clientToken,
+            boundAddr,
+            upstream: options.tunnel.upstream,
+            proxyPort,
+            async stop() {
+                if (timer !== undefined) {
+                    clearInterval(timer);
+                    timer = undefined;
+                }
+                await connector.stop();
+                await options.control.revokeSession(sessionId).catch(() => undefined);
+            },
+        };
+    }
+    catch (error) {
+        if (timer !== undefined) {
+            clearInterval(timer);
+        }
+        await connector.stop().catch(() => undefined);
+        if (sessionId !== "") {
+            await options.control.revokeSession(sessionId).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+export function tunnelMetadata(runtime) {
+    if (runtime === undefined) {
+        return undefined;
+    }
+    return {
+        sessionId: runtime.sessionId,
+        boundAddr: runtime.boundAddr,
+        upstream: runtime.upstream,
+        proxyPort: runtime.proxyPort,
+    };
+}
+function validateTunnelOptions(options) {
+    if (options.upstream.trim() === "") {
+        throw new SandboxValidationError("tunnel.upstream is required");
+    }
+    parseTcpTarget(options.upstream);
+    if (options.proxyPort !== undefined && options.proxyPort < 0) {
+        throw new SandboxValidationError("tunnel.proxyPort must be non-negative");
+    }
+    if (options.ttlSeconds !== undefined && options.ttlSeconds < 0) {
+        throw new SandboxValidationError("tunnel.ttlSeconds must be non-negative");
+    }
+    if (options.readyTimeoutMs !== undefined && options.readyTimeoutMs < 0) {
+        throw new SandboxValidationError("tunnel.readyTimeoutMs must be non-negative");
+    }
+}
+async function waitClientConnected(control, sessionId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const events = await control.listEvents(sessionId, 30);
+        if (events.some((event) => Number(event.event_type ?? 0) === 6)) {
+            return;
+        }
+        await sleep(500);
+    }
+    throw new Error(`tunnel session ${sessionId} did not connect client peer within ${timeoutMs}ms`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/tunnel/session.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type * as grpc from "@grpc/grpc-js";
+import net from "node:net";
+export interface TunnelRelaySessionOptions {
+    upstreamTarget: net.NetConnectOpts;
+    dialTimeoutMs?: number;
+    maxStreams?: number;
+}
+export declare class TunnelRelaySession {
+    private readonly call;
+    private readonly options;
+    private readonly streams;
+    constructor(call: grpc.ClientDuplexStream<Record<string, unknown>, Record<string, unknown>>, options: TunnelRelaySessionOptions);
+    handleFrame(frame: Record<string, unknown>): void;
+    send(frame: Record<string, unknown>): void;
+    closeAll(): void;
+    private openLocal;
+    private writeLocal;
+    private closeLocal;
+    private sendClose;
+}