@donkeylabs/server 2.0.37 → 2.2.0

package/src/core/subprocess-bootstrap.ts

@@ -20,6 +20,7 @@ import {
   KyselyWorkflowAdapter,
   MemoryAuditAdapter,
   MemoryLogsAdapter,
+  createHealth,
 } from "./index";
 import { PluginManager, type CoreServices, type ConfiguredPlugin } from "../core";
 
@@ -96,6 +97,7 @@ export async function bootstrapSubprocess(
   const audit = createAudit({ adapter: auditAdapter });
   const websocket = createWebSocket();
   const storage = createStorage();
+  const health = createHealth({ dbCheck: false });
 
   const core: CoreServices = {
     db,
@@ -114,6 +116,7 @@ export async function bootstrapSubprocess(
     websocket,
     storage,
     logs,
+    health,
   };
 
   workflows.setCore(core);

package/src/core/workflow-executor.ts

@@ -226,6 +226,7 @@ function createIpcEventBridge(socket: Socket, instanceId: string): StateMachineE
         type: "progress",
         instanceId: id,
         timestamp: Date.now(),
+        stepName: currentStep,
         progress,
         completedSteps: completed,
         totalSteps: total,

package/src/core/workflow-state-machine.ts

@@ -751,12 +751,13 @@ export class WorkflowStateMachine {
 
     this.events.onStepCompleted(instanceId, stepName, output, nextStep);
 
-    // Calculate progress
+    // Calculate progress — re-fetch after persist to get accurate count
+    const updated = await this.adapter.getInstance(instanceId);
     const totalSteps = definition.steps.size;
-    const completedSteps = Object.values(instance.stepResults).filter(
-      (r) => r.status === "completed",
-    ).length + 1; // +1 for current step
-    const progress = Math.round((completedSteps / totalSteps) * 100);
+    const completedSteps = updated
+      ? Object.values(updated.stepResults).filter((r) => r.status === "completed").length
+      : 1;
+    const progress = Math.min(100, Math.round((completedSteps / totalSteps) * 100));
 
     this.events.onProgress(instanceId, progress, stepName, completedSteps, totalSteps);
   }

package/src/core/workflows.ts

@@ -1762,20 +1762,21 @@ class WorkflowsImpl implements Workflows {
         await this.emitEvent("workflow.progress", {
           instanceId,
           progress: event.progress,
+          currentStep: event.stepName,
           completedSteps: event.completedSteps,
           totalSteps: event.totalSteps,
         });
         if (this.sse) {
           this.sse.broadcast(`workflow:${instanceId}`, "progress", {
             progress: event.progress,
+            currentStep: event.stepName,
             completedSteps: event.completedSteps,
             totalSteps: event.totalSteps,
           });
           this.sse.broadcast("workflows:all", "workflow.progress", {
             instanceId,
             progress: event.progress,
-            completedSteps: event.completedSteps,
-            totalSteps: event.totalSteps,
+            currentStep: event.stepName,
           });
         }
         break;

package/src/core.ts

@@ -17,6 +17,7 @@ import type { Audit } from "./core/audit";
 import type { WebSocketService } from "./core/websocket";
 import type { Storage } from "./core/storage";
 import type { Logs } from "./core/logs";
+import type { Health } from "./core/health";
 
 // ============================================
 // Auto-detect caller module for plugin define()
@@ -137,6 +138,7 @@ export interface CoreServices {
   websocket: WebSocketService;
   storage: Storage;
   logs: Logs;
+  health: Health;
 }
 
 /**
@@ -182,6 +184,8 @@ export interface GlobalContext {
   ip: string;
   /** Unique request ID */
   requestId: string;
+  /** Trace ID for distributed tracing (from X-Request-Id/X-Trace-Id header, or defaults to requestId) */
+  traceId: string;
   /** Authenticated user (set by auth middleware) */
   user?: any;
   /**
@@ -431,7 +435,11 @@ export type InferService<T> = UnwrapPluginFactory<T> extends { _service: infer S
   : never;
 export type InferSchema<T> = UnwrapPluginFactory<T> extends { _schema: infer S } ? S : never;
 export type InferHandlers<T> = UnwrapPluginFactory<T> extends { handlers?: infer H } ? H : {};
-export type InferMiddleware<T> = UnwrapPluginFactory<T> extends { middleware?: (ctx: any) => infer M } ? M : {};
+export type InferMiddleware<T> = UnwrapPluginFactory<T> extends {
+  middleware?: (ctx: any, service: any) => infer M;
+}
+  ? M
+  : {};
 export type InferDependencies<T> = UnwrapPluginFactory<T> extends { _dependencies: infer D } ? D : readonly [];
 export type InferConfig<T> = T extends (config: infer C) => any ? C : void;
 export type InferEvents<T> = UnwrapPluginFactory<T> extends { events?: infer E } ? E : {};

package/src/generator/index.ts

@@ -19,6 +19,10 @@ export interface RouteInfo {
   outputSource?: string;
   /** SSE event schemas (for sse handler) */
   eventsSource?: Record<string, string>;
+  /** API version (semver) if from a versioned router */
+  version?: string;
+  /** Whether this route version is deprecated */
+  deprecated?: boolean;
 }
 
 export interface EventInfo {

package/src/harness.ts

@@ -17,6 +17,7 @@ import {
   createWebSocket,
   createStorage,
   createLogs,
+  createHealth,
   KyselyJobAdapter,
   KyselyWorkflowAdapter,
   MemoryAuditAdapter,
@@ -71,6 +72,7 @@ export async function createTestHarness(targetPlugin: Plugin, dependencies: Plug
   const websocket = createWebSocket();
   const storage = createStorage(); // Uses memory adapter by default
   const logs = createLogs({ adapter: new MemoryLogsAdapter(), events });
+  const health = createHealth({ dbCheck: false }); // No DB check in unit tests
 
   const core: CoreServices = {
     db,
@@ -89,6 +91,7 @@ export async function createTestHarness(targetPlugin: Plugin, dependencies: Plug
     websocket,
     storage,
     logs,
+    health,
   };
 
   const manager = new PluginManager(core);
@@ -158,28 +161,37 @@ export class TestApiClient extends ApiClientBase {
    * const user = await client.call("users.create", { name: "Test", email: "test@example.com" });
    * ```
    */
-  async call<TOutput = any>(route: string, input: any = {}): Promise<TOutput> {
+  async call<TOutput = any>(
+    route: string,
+    input: any = {},
+    options?: { version?: string }
+  ): Promise<TOutput> {
     const routeDef = this.routeMap.get(route);
     if (!routeDef) {
       throw new Error(`Route not found: ${route}. Available routes: ${[...this.routeMap.keys()].join(", ")}`);
     }
 
+    const versionHeaders: Record<string, string> = {};
+    if (options?.version) {
+      versionHeaders["X-API-Version"] = options.version;
+    }
+
     // Handle different handler types
     if (routeDef.handler === "typed" || routeDef.handler === "formData") {
-      return this.request(route, input);
+      return this.request(route, input, { headers: versionHeaders });
     } else if (routeDef.handler === "stream" || routeDef.handler === "html") {
       const response = await this.rawRequest(route, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: { "Content-Type": "application/json", ...versionHeaders },
         body: JSON.stringify(input),
       });
       return response as any;
     } else if (routeDef.handler === "raw") {
-      const response = await this.rawRequest(route);
+      const response = await this.rawRequest(route, { headers: versionHeaders });
       return response as any;
     }
 
-    return this.request(route, input);
+    return this.request(route, input, { headers: versionHeaders });
   }
 
   /**

package/src/index.ts

@@ -4,6 +4,7 @@
 export {
   AppServer,
   type ServerConfig,
+  type ShutdownConfig,
   // Lifecycle hooks
   type HookContext,
   type OnReadyHandler,
@@ -91,14 +92,34 @@ export function defineConfig(config: DonkeylabsConfig): DonkeylabsConfig {
 // Re-export HttpError for custom error creation
 export { HttpError } from "./core/errors";
 
+// Versioning
+export {
+  parseSemVer,
+  type SemVer,
+  type VersioningConfig,
+  type DeprecationInfo,
+  type RouterOptions,
+} from "./versioning";
+
 // Core services types
 export {
   type Logger,
   type LogLevel,
   type ErrorFactory,
   type ErrorFactories,
+  type EventMetadata,
 } from "./core/index";
 
+// Health checks
+export {
+  type Health,
+  type HealthCheck,
+  type HealthCheckResult,
+  type HealthConfig,
+  type HealthResponse,
+  type HealthStatus,
+} from "./core/health";
+
 // Logs (persistent logging)
 export {
   type Logs,

package/src/router.ts

@@ -2,6 +2,7 @@
 import { z } from "zod";
 import type { GlobalContext, PluginHandlerRegistry } from "./core";
 import type { MiddlewareDefinition } from "./middleware";
+import type { RouterOptions, DeprecationInfo } from "./versioning";
 
 export type ServerContext = GlobalContext;
 
@@ -255,6 +256,8 @@ export interface IRouter {
   getRoutes(): RouteDefinition<any, any, any>[];
   getMetadata(): RouteMetadata[];
   getPrefix(): string;
+  getVersion(): string | undefined;
+  getDeprecation(): DeprecationInfo | undefined;
 }
 
 export class Router implements IRouter {
@@ -262,9 +265,13 @@ export class Router implements IRouter {
   private childRouters: IRouter[] = [];
   private prefix: string;
   private _middlewareStack: MiddlewareDefinition[] = [];
+  private _version?: string;
+  private _deprecated?: DeprecationInfo;
 
-  constructor(prefix: string = "") {
+  constructor(prefix: string = "", options?: RouterOptions) {
     this.prefix = prefix;
+    this._version = options?.version;
+    this._deprecated = options?.deprecated;
   }
 
   route(name: string): IRouteBuilder<this> {
@@ -277,6 +284,11 @@ export class Router implements IRouter {
       const fullPrefix = this.prefix ? `${this.prefix}.${prefixOrRouter}` : prefixOrRouter;
       const childRouter = new Router(fullPrefix);
       childRouter._middlewareStack = [...this._middlewareStack];
+      // Inherit parent version unless child overrides
+      if (this._version && !childRouter._version) {
+        childRouter._version = this._version;
+        childRouter._deprecated = this._deprecated;
+      }
       // Track child router so its routes are included in getRoutes()
       this.childRouters.push(childRouter);
       return childRouter;
@@ -355,6 +367,14 @@ export class Router implements IRouter {
   getPrefix(): string {
     return this.prefix;
   }
+
+  getVersion(): string | undefined {
+    return this._version;
+  }
+
+  getDeprecation(): DeprecationInfo | undefined {
+    return this._deprecated;
+  }
 }
 
 /** Creates a Proxy that intercepts middleware method calls and adds them to the router's middleware stack */
@@ -372,7 +392,7 @@ function createMiddlewareBuilderProxy<TRouter extends Router>(router: TRouter):
   });
 }
 
-export const createRouter = (prefix?: string): IRouter => new Router(prefix);
+export const createRouter = (prefix?: string, options?: RouterOptions): IRouter => new Router(prefix, options);
 
 /**
  * Define a route with type inference for input/output schemas.