@yhyzgn/tikeo 0.1.911

package/README.md

@@ -0,0 +1,9 @@
+# @yhyzgn/tikeo
+
+Node.js SDK aligned with the Rust, Go, Java, and Python Worker SDKs.
+
+- Worker Tunnel client with structured capabilities.
+- Task processors with precise task-scoped logs.
+- Management API client using `x-tikeo-api-key`.
+- SRT/Deno/container/local script runners and fail-closed unavailable handlers.
+- Default `auto`: `srt` for native scripts, `deno` for JavaScript/TypeScript.

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import type { WorkerCapabilities } from "./config.js";
+import { WorkerConfig } from "./config.js";
+import type { ScriptRunnerRegistry } from "./script/index.js";
+import { type TaskOutcome, type TaskProcessor } from "./task.js";
+export interface Registration {
+    clientInstanceId: string;
+    namespace: string;
+    app: string;
+    name: string;
+    region: string;
+    version: string;
+    cluster: string;
+    capabilities: string[];
+    labels: Record<string, string>;
+    structured: WorkerCapabilities;
+}
+export interface Heartbeat {
+    workerId: string;
+    sequence: number;
+    generation: number;
+    fencingToken: string;
+    sentAt: Date;
+}
+export declare class Client {
+    private config;
+    private seq;
+    private open;
+    constructor(config: WorkerConfig);
+    registration(): Registration;
+    startDryRun(processor: TaskProcessor): void;
+    nextHeartbeat(workerId: string, fencingToken: string, generation: number): Heartbeat;
+    close(): void;
+    connectGrpc(): any;
+    connect(): Promise<Session>;
+    private registerMessage;
+}
+export declare class Session {
+    private call;
+    workerId: string;
+    leaseSeconds: number;
+    generation: number;
+    private fencingToken;
+    private heartbeatEveryMs;
+    private sequence;
+    private logSequence;
+    constructor(call: any, workerId: string, leaseSeconds: number, generation: number, fencingToken: string, heartbeatEveryMs: number);
+    sendHeartbeat(): number;
+    startHeartbeat(): () => void;
+    emitTaskLog(instanceId: string, assignmentToken: string, level: string, message: string): number;
+    processNext(processor: TaskProcessor, scripts?: ScriptRunnerRegistry): Promise<TaskOutcome>;
+    close(): void;
+    private emitTaskLogSafely;
+}
+export declare function processDispatchTask(processor: TaskProcessor, scripts: ScriptRunnerRegistry | undefined, task: any, log: (level: string, message: string) => void): Promise<TaskOutcome>;
+export declare function printTaskLogLocally(level: string, message: string): void;
+export declare function grpcTarget(endpoint: string): string;

package/dist/client.js

@@ -0,0 +1,218 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { failed, TaskContext } from "./task.js";
+export class Client {
+    config;
+    seq = 0;
+    open = false;
+    constructor(config) {
+        this.config = config;
+        config.validate();
+        config.normalize();
+    }
+    registration() {
+        return {
+            clientInstanceId: this.config.clientInstanceId,
+            namespace: this.config.namespace,
+            app: this.config.app,
+            name: this.config.name,
+            region: this.config.region,
+            version: this.config.version,
+            cluster: this.config.cluster,
+            capabilities: [...this.config.capabilities],
+            labels: { ...this.config.labels },
+            structured: JSON.parse(JSON.stringify(this.config.structured)),
+        };
+    }
+    startDryRun(processor) {
+        if (!processor)
+            throw new Error("tikeo task processor is required");
+        this.open = true;
+    }
+    nextHeartbeat(workerId, fencingToken, generation) {
+        if (!this.open)
+            throw new Error("tikeo worker client is not started");
+        if (!workerId)
+            throw new Error("tikeo worker id is required");
+        this.seq += 1;
+        return { workerId, sequence: this.seq, generation, fencingToken, sentAt: new Date() };
+    }
+    close() { this.open = false; }
+    connectGrpc() {
+        const proto = loadProto();
+        return new proto.tikeo.worker.v1.WorkerTunnelService(grpcTarget(this.config.endpoint), grpc.credentials.createInsecure());
+    }
+    async connect() {
+        const client = this.connectGrpc();
+        const call = client.OpenTunnel();
+        call.write({ register: this.registerMessage() });
+        const ack = await nextStreamMessage(call);
+        const registered = ack?.registered;
+        if (!registered?.workerId)
+            throw new Error("tikeo worker expected registration ack");
+        return new Session(call, registered.workerId, Number(registered.leaseSeconds ?? 0), Number(registered.generation ?? 0), registered.fencingToken ?? "", this.config.heartbeatEveryMs);
+    }
+    registerMessage() {
+        return {
+            clientInstanceId: this.config.clientInstanceId,
+            app: this.config.app,
+            namespace: this.config.namespace,
+            cluster: this.config.cluster,
+            region: this.config.region,
+            capabilities: [...this.config.capabilities],
+            labels: { ...this.config.labels },
+            structuredCapabilities: {
+                tags: [...this.config.structured.tags],
+                sdkProcessors: this.config.structured.sdkProcessors.map((name) => ({ name })),
+                scriptRunners: this.config.structured.scriptRunners.map((runner) => ({ language: runner.language, sandboxBackend: runner.sandboxBackend })),
+                pluginProcessors: this.config.structured.pluginProcessors.map((plugin) => ({ type: plugin.type, processorNames: [...plugin.processorNames] })),
+            },
+            election: { enabled: true, priority: 100 },
+        };
+    }
+}
+export class Session {
+    call;
+    workerId;
+    leaseSeconds;
+    generation;
+    fencingToken;
+    heartbeatEveryMs;
+    sequence = 0;
+    logSequence = 0;
+    constructor(call, workerId, leaseSeconds, generation, fencingToken, heartbeatEveryMs) {
+        this.call = call;
+        this.workerId = workerId;
+        this.leaseSeconds = leaseSeconds;
+        this.generation = generation;
+        this.fencingToken = fencingToken;
+        this.heartbeatEveryMs = heartbeatEveryMs;
+    }
+    sendHeartbeat() {
+        this.sequence += 1;
+        this.call.write({ heartbeat: { workerId: this.workerId, sequence: this.sequence, generation: this.generation, fencingToken: this.fencingToken } });
+        return this.sequence;
+    }
+    startHeartbeat() {
+        this.sendHeartbeat();
+        const id = setInterval(() => this.sendHeartbeat(), this.heartbeatEveryMs);
+        return () => clearInterval(id);
+    }
+    emitTaskLog(instanceId, assignmentToken, level, message) {
+        this.logSequence += 1;
+        this.call.write({ taskLog: { workerId: this.workerId, instanceId, level: level || "info", message, sequence: this.logSequence, assignmentToken } });
+        return this.logSequence;
+    }
+    async processNext(processor, scripts) {
+        while (true) {
+            const message = await nextStreamMessage(this.call);
+            const task = message?.dispatchTask ?? message?.dispatch_task;
+            if (!task?.instanceId && !task?.instance_id)
+                continue;
+            const normalized = normalizeDispatchTask(task);
+            this.emitTaskLogSafely(normalized, "info", `received task ${normalized.instanceId} processor=${normalized.processorName}`);
+            const outcome = await processDispatchTask(processor, scripts, normalized, (level, msg) => this.emitTaskLogSafely(normalized, level, msg));
+            const level = outcome.success ? "info" : "error";
+            this.emitTaskLogSafely(normalized, level, `completed task ${normalized.instanceId} success=${outcome.success} message=${outcome.message}`);
+            this.call.write({ taskResult: { workerId: this.workerId, instanceId: normalized.instanceId, success: outcome.success, message: outcome.message, assignmentToken: normalized.assignmentToken } });
+            return outcome;
+        }
+    }
+    close() {
+        this.call.write({ unregister: { workerId: this.workerId, generation: this.generation, fencingToken: this.fencingToken } });
+        this.call.end();
+    }
+    emitTaskLogSafely(task, level, message) {
+        printTaskLogLocally(level, message);
+        this.emitTaskLog(task.instanceId, task.assignmentToken, level, message);
+    }
+}
+export async function processDispatchTask(processor, scripts, task, log) {
+    try {
+        const script = task.processorBinding?.script;
+        if (script) {
+            const runner = scripts?.get(script.language);
+            if (!runner)
+                return failed(`script runner is not registered for language: ${script.language}`);
+            return await runner.run({
+                scriptId: script.scriptId,
+                versionId: script.versionId,
+                versionNumber: Number(script.versionNumber),
+                language: script.language,
+                content: script.content,
+                contentSha256: script.contentSha256,
+                timeoutMs: Number(script.timeoutMs || 30_000),
+                maxOutputBytes: Number(script.maxOutputBytes || 1024 * 1024),
+                allowNetwork: Boolean(script.allowNetwork),
+                allowedEnvVars: script.allowedEnvVars ?? [],
+                readOnlyPaths: script.readOnlyPaths ?? [],
+                writablePaths: script.writablePaths ?? [],
+                secretRefs: script.secretRefs ?? [],
+                allowedNetworkHosts: script.allowedNetworkHosts ?? [],
+                sandboxBackend: script.sandboxBackend ?? "",
+                instanceId: task.instanceId,
+                jobId: task.jobId,
+                log,
+            });
+        }
+        return await processor(new TaskContext(task.instanceId, task.jobId, task.processorName || task.jobId, task.payload ?? new Uint8Array(), log));
+    }
+    catch (error) {
+        return failed(error.message);
+    }
+}
+export function printTaskLogLocally(level, message) {
+    const line = `[tikeo-worker] ${message}`;
+    if (level.toLowerCase() === "error")
+        console.error(line);
+    else
+        console.log(line);
+}
+export function grpcTarget(endpoint) {
+    const value = endpoint.trim();
+    if (!value)
+        throw new Error("tikeo worker endpoint is required");
+    try {
+        const url = new URL(value);
+        if (url.protocol === "http:" || url.protocol === "https:")
+            return url.host;
+    }
+    catch {
+        return value;
+    }
+    return value;
+}
+function loadProto() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const protoPath = join(here, "proto", "worker.proto");
+    const definition = protoLoader.loadSync(protoPath, { keepCase: false, longs: Number, enums: String, defaults: true, oneofs: true });
+    return grpc.loadPackageDefinition(definition);
+}
+function nextStreamMessage(call) {
+    return new Promise((resolve, reject) => {
+        const cleanup = (fn, value) => {
+            call.off?.("data", onData);
+            call.off?.("error", onError);
+            call.off?.("end", onEnd);
+            fn(value);
+        };
+        const onData = (message) => cleanup(resolve, message);
+        const onError = (error) => cleanup(reject, error);
+        const onEnd = () => cleanup(reject, new Error("worker tunnel closed"));
+        call.once("data", onData);
+        call.once("error", onError);
+        call.once("end", onEnd);
+    });
+}
+function normalizeDispatchTask(task) {
+    return {
+        instanceId: task.instanceId ?? task.instance_id,
+        jobId: task.jobId ?? task.job_id,
+        payload: task.payload ?? new Uint8Array(),
+        processorName: task.processorName ?? task.processor_name ?? task.jobId ?? task.job_id,
+        processorBinding: task.processorBinding ?? task.processor_binding,
+        assignmentToken: task.assignmentToken ?? task.assignment_token ?? "",
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,50 @@
+export interface ScriptRunnerCapability {
+    language: string;
+    sandboxBackend: string;
+}
+export interface PluginProcessorCapability {
+    type: string;
+    processorNames: string[];
+}
+export interface WorkerCapabilities {
+    tags: string[];
+    sdkProcessors: string[];
+    scriptRunners: ScriptRunnerCapability[];
+    pluginProcessors: PluginProcessorCapability[];
+}
+export interface WorkerConfigInput {
+    endpoint: string;
+    clientInstanceId: string;
+    namespace?: string;
+    app?: string;
+    name?: string;
+    region?: string;
+    version?: string;
+    cluster?: string;
+    capabilities?: string[];
+    labels?: Record<string, string>;
+    structured?: Partial<WorkerCapabilities>;
+    heartbeatEveryMs?: number;
+}
+export declare class WorkerConfig {
+    endpoint: string;
+    clientInstanceId: string;
+    namespace: string;
+    app: string;
+    name: string;
+    region: string;
+    version: string;
+    cluster: string;
+    capabilities: string[];
+    labels: Record<string, string>;
+    structured: WorkerCapabilities;
+    heartbeatEveryMs: number;
+    constructor(input: WorkerConfigInput);
+    addTag(tag: string): void;
+    addSDKProcessor(name: string): void;
+    addScriptRunner(language: string, sandboxBackend: string): void;
+    addPluginProcessor(type: string, processorName: string): void;
+    validate(): void;
+    normalize(): void;
+}
+export declare function localConfig(endpoint: string, clientInstanceId: string): WorkerConfig;

package/dist/config.js

@@ -0,0 +1,89 @@
+export class WorkerConfig {
+    endpoint;
+    clientInstanceId;
+    namespace;
+    app;
+    name;
+    region;
+    version;
+    cluster;
+    capabilities;
+    labels;
+    structured;
+    heartbeatEveryMs;
+    constructor(input) {
+        this.endpoint = input.endpoint;
+        this.clientInstanceId = input.clientInstanceId;
+        this.namespace = input.namespace ?? "default";
+        this.app = input.app ?? "default";
+        this.name = input.name || input.clientInstanceId;
+        this.region = input.region ?? "local";
+        this.version = input.version ?? "dev";
+        this.cluster = input.cluster ?? "local";
+        this.capabilities = [...(input.capabilities ?? [])];
+        this.labels = { ...(input.labels ?? {}) };
+        this.structured = {
+            tags: [...(input.structured?.tags ?? [])],
+            sdkProcessors: [...(input.structured?.sdkProcessors ?? [])],
+            scriptRunners: [...(input.structured?.scriptRunners ?? [])],
+            pluginProcessors: [...(input.structured?.pluginProcessors ?? [])],
+        };
+        this.heartbeatEveryMs = input.heartbeatEveryMs ?? 10_000;
+    }
+    addTag(tag) { appendUnique(this.structured.tags, tag); }
+    addSDKProcessor(name) { appendUnique(this.structured.sdkProcessors, name); }
+    addScriptRunner(language, sandboxBackend) {
+        const item = language.trim();
+        if (!item || this.structured.scriptRunners.some((runner) => runner.language === item))
+            return;
+        this.structured.scriptRunners.push({ language: item, sandboxBackend: sandboxBackend.trim() });
+    }
+    addPluginProcessor(type, processorName) {
+        const processorType = type.trim();
+        const name = processorName.trim();
+        if (!processorType || !name)
+            return;
+        const existing = this.structured.pluginProcessors.find((plugin) => plugin.type === processorType);
+        if (existing)
+            appendUnique(existing.processorNames, name);
+        else
+            this.structured.pluginProcessors.push({ type: processorType, processorNames: [name] });
+    }
+    validate() {
+        const required = {
+            "tikeo worker endpoint": this.endpoint,
+            "tikeo client instance id": this.clientInstanceId,
+            "tikeo worker namespace": this.namespace,
+            "tikeo worker app": this.app,
+            "tikeo worker name": this.name,
+            "tikeo worker cluster": this.cluster,
+        };
+        for (const [label, value] of Object.entries(required)) {
+            if (!value.trim())
+                throw new Error(`${label} is required`);
+        }
+        if (this.heartbeatEveryMs <= 0)
+            throw new Error("tikeo heartbeat interval must be positive");
+    }
+    normalize() {
+        this.capabilities = normalized(this.capabilities);
+        this.structured.tags = normalized(this.structured.tags);
+        this.structured.sdkProcessors = normalized(this.structured.sdkProcessors);
+        for (const plugin of this.structured.pluginProcessors)
+            plugin.processorNames = normalized(plugin.processorNames);
+    }
+}
+export function localConfig(endpoint, clientInstanceId) {
+    return new WorkerConfig({ endpoint, clientInstanceId });
+}
+function appendUnique(values, value) {
+    const item = value.trim();
+    if (item && !values.includes(item))
+        values.push(item);
+}
+function normalized(values) {
+    const out = [];
+    for (const value of values)
+        appendUnique(out, value);
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./config.js";
+export * from "./management.js";
+export * from "./script/index.js";
+export * from "./task.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./config.js";
+export * from "./management.js";
+export * from "./script/index.js";
+export * from "./task.js";

package/dist/management.d.ts

@@ -0,0 +1,45 @@
+export declare const API_KEY_HEADER = "x-tikeo-api-key";
+export interface JobRetryPolicy {
+    enabled: boolean;
+    maxAttempts: number;
+    initialDelaySeconds: number;
+    backoffMultiplier: number;
+    maxDelaySeconds: number;
+}
+export declare function defaultJobRetryPolicy(): JobRetryPolicy;
+export interface JobDefinition {
+    id: string;
+    namespace: string;
+    app: string;
+    name: string;
+    scheduleType: string;
+    scheduleExpr?: string | null;
+    processorName?: string | null;
+    processorType?: string | null;
+    scriptId?: string | null;
+    enabled: boolean;
+    retryPolicy?: JobRetryPolicy | null;
+}
+export interface CreateJobRequest {
+    name: string;
+    scheduleType: string;
+    scheduleExpr?: string | null;
+    processorName?: string | null;
+    processorType?: string | null;
+    scriptId?: string | null;
+    enabled?: boolean;
+    retryPolicy?: JobRetryPolicy | null;
+}
+export declare function apiJob(name: string, processorName: string): CreateJobRequest;
+export declare function pluginApiJob(name: string, processorType: string, processorName: string): CreateJobRequest;
+export declare function scriptApiJob(name: string, scriptId: string): CreateJobRequest;
+export declare class ManagementClient {
+    private apiKey;
+    private namespace;
+    private app;
+    private endpoint;
+    constructor(endpoint: string, apiKey: string, namespace?: string, app?: string);
+    listJobs(): Promise<JobDefinition[]>;
+    createJob(request: CreateJobRequest): Promise<JobDefinition>;
+    private send;
+}

package/dist/management.js

@@ -0,0 +1,63 @@
+export const API_KEY_HEADER = "x-tikeo-api-key";
+export function defaultJobRetryPolicy() {
+    return { enabled: true, maxAttempts: 3, initialDelaySeconds: 5, backoffMultiplier: 2, maxDelaySeconds: 60 };
+}
+export function apiJob(name, processorName) {
+    return { name, scheduleType: "api", processorName, enabled: true, retryPolicy: defaultJobRetryPolicy() };
+}
+export function pluginApiJob(name, processorType, processorName) {
+    return { name, scheduleType: "api", processorType, processorName, enabled: true, retryPolicy: defaultJobRetryPolicy() };
+}
+export function scriptApiJob(name, scriptId) {
+    return { name, scheduleType: "api", scriptId, enabled: true, retryPolicy: defaultJobRetryPolicy() };
+}
+export class ManagementClient {
+    apiKey;
+    namespace;
+    app;
+    endpoint;
+    constructor(endpoint, apiKey, namespace = "default", app = "default") {
+        this.apiKey = apiKey;
+        this.namespace = namespace;
+        this.app = app;
+        this.endpoint = endpoint.trim().replace(/\/$/, "");
+        this.namespace = namespace.trim() || "default";
+        this.app = app.trim() || "default";
+    }
+    async listJobs() {
+        const data = await this.send("GET", "/jobs");
+        const items = Array.isArray(data?.items) ? data.items : [];
+        return items.filter((job) => job.namespace === this.namespace && job.app === this.app);
+    }
+    async createJob(request) {
+        const payload = {
+            namespace: this.namespace,
+            app: this.app,
+            name: request.name,
+            scheduleType: request.scheduleType,
+            scheduleExpr: request.scheduleExpr,
+            processorName: request.processorName,
+            processorType: request.processorType,
+            scriptId: request.scriptId,
+            enabled: request.enabled,
+            retryPolicy: request.retryPolicy,
+        };
+        for (const key of Object.keys(payload))
+            if (payload[key] === undefined || payload[key] === null)
+                delete payload[key];
+        return this.send("POST", "/jobs", payload);
+    }
+    async send(method, path, body) {
+        const response = await fetch(`${this.endpoint}/api/v1${path}`, {
+            method,
+            headers: { accept: "application/json", [API_KEY_HEADER]: this.apiKey, ...(body ? { "content-type": "application/json" } : {}) },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const envelope = await response.json();
+        if (!response.ok || envelope.code !== 0)
+            throw new Error(`tikeo management request failed: status=${response.status} message=${envelope.message ?? ""}`);
+        if (envelope.data === undefined || envelope.data === null)
+            throw new Error("tikeo management response data was null");
+        return envelope.data;
+    }
+}