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

package/dist/node/exec.js

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError, SandboxExecError } from "../errors/index.js";
+import { unary } from "../generated/proto.js";
+import { normalizeCommand } from "../validation.js";
+export async function exec(ctx, command, options = {}) {
+    const argv = normalizeCommand(command);
+    try {
+        const response = await ctx.withAuthRetry(options.leaseTtlSeconds ?? 300, async (client) => unary(client, "Exec", ctx.authRequest({
+            spec: execSpec(argv, options),
+        }), options.rpcTimeoutMs));
+        const result = execResult(response);
+        if (options.check === true && result.exitCode !== 0) {
+            throw new SandboxExecError(argv, result);
+        }
+        return result;
+    }
+    catch (error) {
+        if (error instanceof SandboxExecError) {
+            throw error;
+        }
+        throw mapRpcError(error, "sandbox exec", ctx.allocationId);
+    }
+}
+export async function execImage(ctx, image, command, options = {}) {
+    if (image.trim() === "") {
+        throw new Error("image is required");
+    }
+    const argv = normalizeCommand(command);
+    try {
+        const response = await ctx.withAuthRetry(options.leaseTtlSeconds ?? 300, async (client) => unary(client, "ExecImage", ctx.authRequest({
+            spec: imageProcessSpec(image, argv, options),
+        }), options.rpcTimeoutMs));
+        const result = execResult(response);
+        if (options.check === true && result.exitCode !== 0) {
+            throw new SandboxExecError(argv, result);
+        }
+        return result;
+    }
+    catch (error) {
+        if (error instanceof SandboxExecError) {
+            throw error;
+        }
+        throw mapRpcError(error, "sandbox exec image", ctx.allocationId);
+    }
+}
+export function execSpec(argv, options) {
+    return {
+        argv,
+        env: options.env ?? {},
+        cwd: options.cwd ?? "",
+        timeout_seconds: options.timeoutSeconds ?? 0,
+        tty: options.tty ?? false,
+        user: options.user ?? "",
+    };
+}
+export function imageProcessSpec(image, argv, options) {
+    return {
+        image,
+        argv,
+        env: options.env ?? {},
+        cwd: options.cwd ?? "",
+        timeout_seconds: options.timeoutSeconds ?? 0,
+        tty: options.tty ?? false,
+        user: options.user ?? "",
+        mounts: imageProcessMounts(options.mounts),
+    };
+}
+function imageProcessMounts(mounts) {
+    const effective = mounts ?? [{ sandboxPath: "/workspace", targetPath: "/workspace" }];
+    return effective.map((mount) => ({
+        sandbox_path: mount.sandboxPath,
+        target_path: mount.targetPath,
+        readonly: mount.readonly ?? false,
+        options: [...(mount.options ?? [])],
+    }));
+}
+export function execResult(response) {
+    const stdout = Buffer.from(response.stdout ?? []);
+    const stderr = Buffer.from(response.stderr ?? []);
+    return {
+        exitCode: Number(response.exit_code ?? 0),
+        stdout,
+        stderr,
+        stdoutTruncated: response.stdout_truncated === true,
+        stderrTruncated: response.stderr_truncated === true,
+        stdoutText: (encoding = "utf8") => stdout.toString(encoding),
+        stderrText: (encoding = "utf8") => stderr.toString(encoding),
+    };
+}

package/dist/node/files.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ChmodOptions, CopyOptions, MkdirOptions, MoveOptions, RemoveOptions, SandboxFileInfo, TouchOptions, WriteFileOptions } from "../types.js";
+import type { NodeClientContext } from "./context.js";
+export declare function stat(ctx: NodeClientContext, path: string): Promise<SandboxFileInfo>;
+export declare function listDir(ctx: NodeClientContext, path: string): Promise<SandboxFileInfo[]>;
+export declare function exists(ctx: NodeClientContext, path: string): Promise<boolean>;
+export declare function readFile(ctx: NodeClientContext, path: string): Promise<Buffer>;
+export declare function writeFile(ctx: NodeClientContext, path: string, data: Buffer | Uint8Array | string, options?: WriteFileOptions): Promise<void>;
+export declare function mkdir(ctx: NodeClientContext, path: string, options?: MkdirOptions): Promise<void>;
+export declare function remove(ctx: NodeClientContext, path: string, options?: RemoveOptions): Promise<void>;
+export declare function copy(ctx: NodeClientContext, srcPath: string, dstPath: string, options?: CopyOptions): Promise<void>;
+export declare function move(ctx: NodeClientContext, srcPath: string, dstPath: string, options?: MoveOptions): Promise<void>;
+export declare function chmod(ctx: NodeClientContext, path: string, mode: number, options?: ChmodOptions): Promise<void>;
+export declare function touch(ctx: NodeClientContext, path: string, options?: TouchOptions): Promise<void>;

package/dist/node/files.js

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError } from "../errors/index.js";
+import { unary } from "../generated/proto.js";
+import { nonEmptyPath } from "../validation.js";
+export async function stat(ctx, path) {
+    const response = await fileUnary(ctx, "StatFile", { path: nonEmptyPath(path) });
+    return fileInfo(response.info);
+}
+export async function listDir(ctx, path) {
+    const response = await fileUnary(ctx, "ListDir", { path: nonEmptyPath(path) });
+    return (response.entries ?? []).map(fileInfo);
+}
+export async function exists(ctx, path) {
+    const response = await fileUnary(ctx, "Exists", { path: nonEmptyPath(path) });
+    return response.exists === true;
+}
+export async function readFile(ctx, path) {
+    const response = await fileUnary(ctx, "ReadFile", { path: nonEmptyPath(path) });
+    return Buffer.from(response.data ?? []);
+}
+export async function writeFile(ctx, path, data, options = {}) {
+    await fileUnary(ctx, "WriteFile", {
+        path: nonEmptyPath(path),
+        data: Buffer.isBuffer(data) ? data : Buffer.from(data),
+        create_parents: options.createParents ?? false,
+    });
+}
+export async function mkdir(ctx, path, options = {}) {
+    await fileUnary(ctx, "Mkdir", { path: nonEmptyPath(path), parents: options.parents ?? false });
+}
+export async function remove(ctx, path, options = {}) {
+    await fileUnary(ctx, "Remove", {
+        path: nonEmptyPath(path),
+        recursive: options.recursive ?? false,
+        force: options.force ?? false,
+    });
+}
+export async function copy(ctx, srcPath, dstPath, options = {}) {
+    await fileUnary(ctx, "Copy", {
+        src_path: nonEmptyPath(srcPath),
+        dst_path: nonEmptyPath(dstPath),
+        recursive: options.recursive ?? false,
+        overwrite: options.overwrite ?? false,
+    });
+}
+export async function move(ctx, srcPath, dstPath, options = {}) {
+    await fileUnary(ctx, "Move", {
+        src_path: nonEmptyPath(srcPath),
+        dst_path: nonEmptyPath(dstPath),
+        overwrite: options.overwrite ?? false,
+    });
+}
+export async function chmod(ctx, path, mode, options = {}) {
+    await fileUnary(ctx, "Chmod", {
+        path: nonEmptyPath(path),
+        mode,
+        recursive: options.recursive ?? false,
+    });
+}
+export async function touch(ctx, path, options = {}) {
+    await fileUnary(ctx, "Touch", {
+        path: nonEmptyPath(path),
+        create: options.create ?? true,
+        mtime_ns: options.mtimeNs ?? 0,
+    });
+}
+async function fileUnary(ctx, method, payload) {
+    try {
+        return await ctx.withAuthRetry(300, (client) => unary(client, method, ctx.authRequest(payload)));
+    }
+    catch (error) {
+        throw mapRpcError(error, `sandbox ${method}`, ctx.allocationId);
+    }
+}
+function fileInfo(input) {
+    return {
+        path: String(input?.path ?? ""),
+        kind: fileKind(input?.kind),
+        size: Number(input?.size ?? 0),
+        mode: Number(input?.mode ?? 0),
+        mtimeNs: Number(input?.mtime_ns ?? 0),
+    };
+}
+function fileKind(kind) {
+    switch (kind) {
+        case 1:
+            return "file";
+        case 2:
+            return "directory";
+        case 3:
+            return "symlink";
+        case 4:
+            return "other";
+        default:
+            return "unspecified";
+    }
+}

package/dist/node/process.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type * as grpc from "@grpc/grpc-js";
+import type { ProcessEvent, ProcessResult } from "../types.js";
+export interface SandboxProcessOptions {
+    allocationId: string;
+    call: grpc.ClientDuplexStream<Record<string, unknown>, Record<string, unknown>>;
+    closeClient: () => void;
+}
+export declare class SandboxProcess {
+    readonly allocationId: string;
+    private readonly call;
+    private readonly closeClient;
+    private readonly queue;
+    private readonly waiters;
+    private error;
+    private ended;
+    private exit?;
+    constructor(options: SandboxProcessOptions);
+    write(data: Buffer | Uint8Array | string): void;
+    closeStdin(): void;
+    resize(cols: number, rows: number): void;
+    signal(signal: string): void;
+    terminate(): void;
+    kill(): void;
+    waitReady(): Promise<void>;
+    wait(): Promise<ProcessResult>;
+    close(): Promise<void>;
+    events(): AsyncIterable<ProcessEvent>;
+    private nextEvent;
+    private enqueue;
+    private finish;
+}

package/dist/node/process.js

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError } from "../errors/index.js";
+export class SandboxProcess {
+    allocationId;
+    call;
+    closeClient;
+    queue = [];
+    waiters = [];
+    error;
+    ended = false;
+    exit;
+    constructor(options) {
+        this.allocationId = options.allocationId;
+        this.call = options.call;
+        this.closeClient = options.closeClient;
+        this.call.on("data", (message) => this.enqueue(processEvent(message)));
+        this.call.on("error", (error) => {
+            this.error = error;
+            this.finish();
+        });
+        this.call.on("end", () => this.finish());
+    }
+    write(data) {
+        this.call.write({ stdin: Buffer.isBuffer(data) ? data : Buffer.from(data) });
+    }
+    closeStdin() {
+        this.call.write({ close_stdin: true });
+    }
+    resize(cols, rows) {
+        this.call.write({ resize: { cols, rows } });
+    }
+    signal(signal) {
+        this.call.write({ signal: { signal } });
+    }
+    terminate() {
+        this.signal("TERM");
+    }
+    kill() {
+        this.signal("KILL");
+    }
+    async waitReady() {
+        const next = await this.nextEvent();
+        if (next.done === true) {
+            if (this.error !== undefined) {
+                throw this.error;
+            }
+            throw new Error("sandbox process stream ended before ready");
+        }
+        if (next.value.kind !== "ready") {
+            this.queue.unshift(next.value);
+        }
+    }
+    async wait() {
+        if (this.exit !== undefined) {
+            return this.exit;
+        }
+        for await (const event of this.events()) {
+            if (event.kind === "exit") {
+                return { exitCode: event.exitCode, message: event.message };
+            }
+        }
+        if (this.error !== undefined) {
+            throw mapRpcError(this.error, "sandbox process", this.allocationId);
+        }
+        throw new Error("sandbox process stream ended before exit");
+    }
+    async close() {
+        this.call.end();
+        this.closeClient();
+    }
+    async *events() {
+        while (true) {
+            const next = await this.nextEvent();
+            if (next.done === true) {
+                if (this.error !== undefined) {
+                    throw mapRpcError(this.error, "sandbox process", this.allocationId);
+                }
+                return;
+            }
+            yield next.value;
+            if (next.value.kind === "exit") {
+                return;
+            }
+        }
+    }
+    nextEvent() {
+        const event = this.queue.shift();
+        if (event !== undefined) {
+            return Promise.resolve({ done: false, value: event });
+        }
+        if (this.ended) {
+            return Promise.resolve({ done: true, value: undefined });
+        }
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    enqueue(event) {
+        if (event.kind === "exit") {
+            this.exit = { exitCode: event.exitCode, message: event.message };
+            this.call.end();
+            this.closeClient();
+        }
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            waiter({ done: false, value: event });
+        }
+        else {
+            this.queue.push(event);
+        }
+    }
+    finish() {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        this.closeClient();
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ done: true, value: undefined });
+        }
+    }
+}
+function processEvent(message) {
+    if ("ready" in message) {
+        return { kind: "ready" };
+    }
+    if ("stdout" in message) {
+        return { kind: "stdout", data: Buffer.from(message.stdout ?? []) };
+    }
+    if ("stderr" in message) {
+        return { kind: "stderr", data: Buffer.from(message.stderr ?? []) };
+    }
+    if ("exit" in message) {
+        const exit = message.exit;
+        return {
+            kind: "exit",
+            exitCode: Number(exit?.exit_code ?? 0),
+            message: String(exit?.message ?? ""),
+        };
+    }
+    return { kind: "ready" };
+}

package/dist/node/streams.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as grpc from "@grpc/grpc-js";
+export declare function uploadArchiveStream(client: grpc.Client, open: Record<string, unknown>, chunks: AsyncIterable<Buffer | Uint8Array>, deadlineMs: number | undefined): Promise<void>;
+export declare function downloadArchiveStream(client: grpc.Client, request: Record<string, unknown>, deadlineMs: number | undefined): AsyncIterable<Buffer>;

package/dist/node/streams.js

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as grpc from "@grpc/grpc-js";
+export function uploadArchiveStream(client, open, chunks, deadlineMs) {
+    return new Promise((resolve, reject) => {
+        const callback = (error) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve();
+            }
+        };
+        const fn = client.UploadArchive;
+        const call = deadlineMs === undefined
+            ? fn.call(client, callback)
+            : fn.call(client, new grpc.Metadata(), { deadline: Date.now() + deadlineMs }, callback);
+        void (async () => {
+            try {
+                await writeStream(call, { open });
+                for await (const chunk of chunks) {
+                    if (chunk.byteLength > 0) {
+                        await writeStream(call, { chunk: Buffer.from(chunk) });
+                    }
+                }
+                call.end();
+            }
+            catch (error) {
+                call.destroy(error instanceof Error ? error : new Error(String(error)));
+                reject(error);
+            }
+        })();
+    });
+}
+export function downloadArchiveStream(client, request, deadlineMs) {
+    const fn = client.DownloadArchive;
+    const call = deadlineMs === undefined
+        ? fn.call(client, request)
+        : fn.call(client, request, new grpc.Metadata(), { deadline: Date.now() + deadlineMs });
+    return streamChunks(call);
+}
+async function* streamChunks(call) {
+    for await (const message of call) {
+        const chunk = message.chunk;
+        if (chunk !== undefined && chunk.byteLength > 0) {
+            yield Buffer.from(chunk);
+        }
+    }
+}
+function writeStream(stream, value) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            stream.off("error", onError);
+            reject(error);
+        };
+        stream.once("error", onError);
+        stream.write(value, (error) => {
+            stream.off("error", onError);
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}

package/dist/proto/axern/common/file/v1/file.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package axern.common.file.v1;
+
+option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/common/file/v1;filev1";
+
+enum SandboxFileKind {
+  SANDBOX_FILE_KIND_UNSPECIFIED = 0;
+  SANDBOX_FILE_KIND_FILE = 1;
+  SANDBOX_FILE_KIND_DIRECTORY = 2;
+  SANDBOX_FILE_KIND_SYMLINK = 3;
+  SANDBOX_FILE_KIND_OTHER = 4;
+}
+
+enum SandboxArchiveFormat {
+  SANDBOX_ARCHIVE_FORMAT_UNSPECIFIED = 0;
+  SANDBOX_ARCHIVE_FORMAT_TAR = 1;
+}
+
+enum SandboxArchiveSymlinkPolicy {
+  SANDBOX_ARCHIVE_SYMLINK_POLICY_UNSPECIFIED = 0;
+  SANDBOX_ARCHIVE_SYMLINK_POLICY_REJECT = 1;
+}
+
+message SandboxFileInfo {
+  string path = 1;
+  SandboxFileKind kind = 2;
+  int64 size = 3;
+  uint32 mode = 4;
+  int64 mtime_ns = 5;
+}

package/dist/proto/axern/control/admin/v1/allocation_lifecycle.proto

@@ -0,0 +1,91 @@
+syntax = "proto3";
+
+package axern.control.admin.v1;
+
+option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/control/admin/v1;adminv1";
+
+import "google/protobuf/timestamp.proto";
+
+enum AllocationLifecycleRetryOwnerType {
+  ALLOCATION_LIFECYCLE_RETRY_OWNER_TYPE_UNSPECIFIED = 0;
+  ALLOCATION_LIFECYCLE_RETRY_OWNER_TYPE_RUN = 1;
+  ALLOCATION_LIFECYCLE_RETRY_OWNER_TYPE_SERVICE = 2;
+}
+
+enum AllocationLifecycleRetryReason {
+  ALLOCATION_LIFECYCLE_RETRY_REASON_UNSPECIFIED = 0;
+  ALLOCATION_LIFECYCLE_RETRY_REASON_CREATE = 1;
+  ALLOCATION_LIFECYCLE_RETRY_REASON_DELETE = 2;
+}
+
+message AllocationLifecycleRetry {
+  string allocation_id = 1;
+  string owner_id = 2;
+  AllocationLifecycleRetryOwnerType owner_type = 3;
+  string environment_id = 4;
+  AllocationLifecycleRetryReason reason = 5;
+  string node_id = 6;
+  string node_target = 7;
+  int64 attempt = 8;
+  int32 reconcile_attempts = 9;
+  string last_error = 10;
+  google.protobuf.Timestamp next_run_at = 11;
+  google.protobuf.Timestamp created_at = 12;
+  google.protobuf.Timestamp updated_at = 13;
+  int64 age_seconds = 14;
+  bool due = 15;
+  bool clearable = 16;
+  string clear_blocked_reason = 17;
+}
+
+message AllocationLifecycleRetryFilter {
+  AllocationLifecycleRetryOwnerType owner_type = 1;
+  AllocationLifecycleRetryReason reason = 2;
+  bool due_only = 3;
+}
+
+message ListAllocationLifecycleRetriesRequest {
+  AllocationLifecycleRetryFilter filter = 1;
+  int32 limit = 2;
+}
+
+message ListAllocationLifecycleRetriesResponse {
+  repeated AllocationLifecycleRetry retries = 1;
+}
+
+message ForceAllocationLifecycleRetryRequest {
+  string allocation_id = 1;
+  AllocationLifecycleRetryReason reason = 2;
+  string operator_reason = 3;
+}
+
+message ForceAllocationLifecycleRetryResponse {
+  AllocationLifecycleRetry retry = 1;
+}
+
+message FailAllocationLifecycleRetryRequest {
+  string allocation_id = 1;
+  AllocationLifecycleRetryReason reason = 2;
+  string operator_reason = 3;
+}
+
+message FailAllocationLifecycleRetryResponse {
+  AllocationLifecycleRetry failed_retry = 1;
+}
+
+message ClearAllocationLifecycleRetryRequest {
+  string allocation_id = 1;
+  AllocationLifecycleRetryReason reason = 2;
+  string operator_reason = 3;
+}
+
+message ClearAllocationLifecycleRetryResponse {
+  AllocationLifecycleRetry cleared_retry = 1;
+}
+
+service AllocationLifecycleAdmin {
+  rpc ListAllocationLifecycleRetries(ListAllocationLifecycleRetriesRequest) returns (ListAllocationLifecycleRetriesResponse) {}
+  rpc ForceAllocationLifecycleRetry(ForceAllocationLifecycleRetryRequest) returns (ForceAllocationLifecycleRetryResponse) {}
+  rpc FailAllocationLifecycleRetry(FailAllocationLifecycleRetryRequest) returns (FailAllocationLifecycleRetryResponse) {}
+  rpc ClearAllocationLifecycleRetry(ClearAllocationLifecycleRetryRequest) returns (ClearAllocationLifecycleRetryResponse) {}
+}

package/dist/proto/axern/control/admin/v1/audit.proto

@@ -0,0 +1,53 @@
+syntax = "proto3";
+
+package axern.control.admin.v1;
+
+option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/control/admin/v1;adminv1";
+
+import "google/protobuf/timestamp.proto";
+
+enum AdminAuditOperation {
+  ADMIN_AUDIT_OPERATION_UNSPECIFIED = 0;
+  ADMIN_AUDIT_OPERATION_FORCE_ALLOCATION_LIFECYCLE_RETRY = 1;
+  ADMIN_AUDIT_OPERATION_FAIL_ALLOCATION_LIFECYCLE_RETRY = 2;
+  ADMIN_AUDIT_OPERATION_CLEAR_ALLOCATION_LIFECYCLE_RETRY = 3;
+  ADMIN_AUDIT_OPERATION_RETRY_STORAGE_BINDING = 4;
+  ADMIN_AUDIT_OPERATION_PURGE_SERVICE = 5;
+  ADMIN_AUDIT_OPERATION_RETIRE_NODE = 6;
+}
+
+enum AdminAuditTargetType {
+  ADMIN_AUDIT_TARGET_TYPE_UNSPECIFIED = 0;
+  ADMIN_AUDIT_TARGET_TYPE_ALLOCATION = 1;
+  ADMIN_AUDIT_TARGET_TYPE_STORAGE_BINDING = 2;
+  ADMIN_AUDIT_TARGET_TYPE_SERVICE = 3;
+  ADMIN_AUDIT_TARGET_TYPE_NODE = 4;
+}
+
+message AdminAuditEvent {
+  string event_id = 1;
+  AdminAuditOperation operation = 2;
+  AdminAuditTargetType target_type = 3;
+  string target_id = 4;
+  string operator_reason = 5;
+  google.protobuf.Timestamp created_at = 6;
+}
+
+message AdminAuditEventFilter {
+  AdminAuditOperation operation = 1;
+  AdminAuditTargetType target_type = 2;
+  string target_id = 3;
+}
+
+message ListAdminAuditEventsRequest {
+  AdminAuditEventFilter filter = 1;
+  int32 limit = 2;
+}
+
+message ListAdminAuditEventsResponse {
+  repeated AdminAuditEvent events = 1;
+}
+
+service AdminAudit {
+  rpc ListAdminAuditEvents(ListAdminAuditEventsRequest) returns (ListAdminAuditEventsResponse) {}
+}