vector-framework 1.2.1 → 1.2.3

package/src/checkpoint/resolver.ts

@@ -0,0 +1,124 @@
+import type { CheckpointManager } from './manager';
+import type { CheckpointProcessManager } from './process-manager';
+
+const DEFAULT_VERSION_HEADER = 'x-vector-checkpoint-version';
+const FALLBACK_VERSION_HEADER = 'x-vector-checkpoint';
+
+export interface CheckpointResolverOptions {
+  versionHeader?: string;
+  cacheKeyOverride?: boolean;
+}
+
+export class CheckpointResolver {
+  private manager: CheckpointManager;
+  private processManager: CheckpointProcessManager;
+  private versionHeader: string;
+  private cacheKeyOverride: boolean;
+  private allowFallbackVersionHeader: boolean;
+  private pendingVersionResolves: Map<string, Promise<string | null>> = new Map();
+
+  constructor(
+    manager: CheckpointManager,
+    processManager: CheckpointProcessManager,
+    options: CheckpointResolverOptions = {}
+  ) {
+    this.manager = manager;
+    this.processManager = processManager;
+    this.versionHeader = normalizeHeaderName(options.versionHeader ?? DEFAULT_VERSION_HEADER);
+    this.cacheKeyOverride = options.cacheKeyOverride === true;
+    this.allowFallbackVersionHeader = options.versionHeader === undefined;
+  }
+
+  async resolve(request: Request): Promise<string | null> {
+    const requestedVersion = this.getRequestedVersion(request);
+    if (!requestedVersion) {
+      return null;
+    }
+    return await this.resolveVersion(requestedVersion);
+  }
+
+  getRequestedVersion(request: Request): string | null {
+    return this.getRequestedHeader(request)?.value ?? null;
+  }
+
+  getCacheKeyOverrideValue(request: Request): string | null {
+    if (!this.cacheKeyOverride) {
+      return null;
+    }
+
+    const requestedHeader = this.getRequestedHeader(request);
+    if (!requestedHeader) {
+      return null;
+    }
+
+    return `${requestedHeader.name}:${requestedHeader.value}`;
+  }
+
+  private getRequestedHeader(request: Request): { name: string; value: string } | null {
+    const primary = request.headers.get(this.versionHeader);
+    if (primary && primary.trim().length > 0) {
+      return { name: this.versionHeader, value: primary.trim() };
+    }
+
+    if (this.allowFallbackVersionHeader && this.versionHeader !== FALLBACK_VERSION_HEADER) {
+      const fallback = request.headers.get(FALLBACK_VERSION_HEADER);
+      if (fallback && fallback.trim().length > 0) {
+        return { name: FALLBACK_VERSION_HEADER, value: fallback.trim() };
+      }
+    }
+
+    return null;
+  }
+
+  private async resolveVersion(version: string): Promise<string | null> {
+    let running = this.processManager.getRunning(version);
+    if (!running) {
+      const pending = this.pendingVersionResolves.get(version);
+      if (pending) {
+        const socketPath = await pending;
+        if (!socketPath) {
+          return null;
+        }
+
+        this.processManager.markUsed(version);
+        return socketPath;
+      }
+
+      const pendingResolve = (async (): Promise<string | null> => {
+        try {
+          const manifest = await this.manager.readManifest(version);
+          const spawned = await this.processManager.spawn(manifest, this.manager.getStorageDir());
+          return spawned.socketPath;
+        } catch {
+          return null;
+        }
+      })();
+
+      this.pendingVersionResolves.set(version, pendingResolve);
+      const socketPath = await pendingResolve;
+      this.pendingVersionResolves.delete(version);
+
+      if (!socketPath) {
+        return null;
+      }
+
+      this.processManager.markUsed(version);
+      return socketPath;
+    }
+
+    this.processManager.markUsed(version);
+    return running.socketPath;
+  }
+
+  /**
+   * Legacy no-op retained for compatibility with tests and existing integrations.
+   */
+  invalidateCache(): void {
+    // No caching, so nothing to invalidate.
+  }
+}
+
+function normalizeHeaderName(value: string): string {
+  const normalized = value.trim().toLowerCase();
+  return normalized.length > 0 ? normalized : DEFAULT_VERSION_HEADER;
+}

package/src/checkpoint/socket-path.ts

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+const CHECKPOINT_SOCKET_FILE = 'run.sock';
+const UNIX_SOCKET_PATH_MAX_BYTES = 103;
+
+function toAbsolute(dir: string): string {
+  return isAbsolute(dir) ? dir : resolve(dir);
+}
+
+function unixSocketWithinLimit(path: string): boolean {
+  return Buffer.byteLength(path, 'utf8') <= UNIX_SOCKET_PATH_MAX_BYTES;
+}
+
+function socketFileName(storageDir: string, version: string): string {
+  const versionLabel = version
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-+|-+$)/g, '')
+    .slice(0, 12);
+
+  const digest = createHash('sha256').update(storageDir).update('\0').update(version).digest('hex').slice(0, 16);
+  const label = versionLabel.length > 0 ? `${versionLabel}-` : '';
+  return `vector-${label}${digest}.sock`;
+}
+
+function candidateSocketRoots(): string[] {
+  const roots = new Set<string>();
+  const override = process.env.VECTOR_CHECKPOINT_SOCKET_DIR?.trim();
+  if (override) {
+    roots.add(toAbsolute(override));
+  }
+
+  // Prefer short, stable roots before os.tmpdir(), especially on macOS where tmpdir can be long.
+  if (process.platform !== 'win32') {
+    roots.add('/tmp');
+    roots.add('/private/tmp');
+  }
+
+  roots.add(toAbsolute(tmpdir()));
+  return [...roots];
+}
+
+export function resolveCheckpointSocketPath(storageDir: string, version: string): string {
+  const defaultPath = join(storageDir, version, CHECKPOINT_SOCKET_FILE);
+  if (process.platform === 'win32' || unixSocketWithinLimit(defaultPath)) {
+    return defaultPath;
+  }
+
+  const fileName = socketFileName(storageDir, version);
+  for (const root of candidateSocketRoots()) {
+    const candidate = join(root, fileName);
+    if (unixSocketWithinLimit(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Last resort: retain deterministic socket naming even if the environment has unusually long temp paths.
+  return join('/tmp', fileName);
+}

package/src/checkpoint/types.ts

@@ -0,0 +1,63 @@
+export const CHECKPOINT_FORMAT_VERSION = 1;
+
+export type CheckpointCompressionCodec = 'none' | 'gzip';
+
+export interface CheckpointManifest {
+  formatVersion: number;
+  version: string;
+  createdAt: string;
+  entrypoint: string;
+  routes: CheckpointRouteRecord[];
+  assets: CheckpointAssetRecord[];
+  bundleHash: string;
+  bundleSize: number;
+  checkpointArchivePath?: string;
+  checkpointArchiveHash?: string;
+  checkpointArchiveSize?: number;
+  checkpointArchiveCodec?: CheckpointCompressionCodec;
+}
+
+export interface CheckpointRouteRecord {
+  method: string;
+  path: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckpointAssetRecord {
+  type: 'embedded' | 'sidecar';
+  logicalPath: string;
+  // Legacy field kept for compatibility with existing tests/fixtures.
+  storedPath: string;
+  // Legacy field kept for compatibility with existing tests/fixtures.
+  hash: string;
+  // Legacy field kept for compatibility with existing tests/fixtures.
+  size: number;
+  contentHash?: string;
+  contentSize?: number;
+  blobHash?: string;
+  blobSize?: number;
+  blobPath?: string;
+  codec?: CheckpointCompressionCodec;
+  materializedPath?: string;
+}
+
+export interface CheckpointConfig {
+  enabled?: boolean;
+  storageDir?: string;
+  maxCheckpoints?: number;
+  versionHeader?: string;
+  idleTimeoutMs?: number;
+  cacheKeyOverride?: boolean;
+}
+
+export interface CheckpointPublishOptions {
+  version: string;
+  routesDir: string;
+  embeddedAssetPaths?: string[];
+  sidecarAssetPaths?: string[];
+}
+
+export interface ActivePointer {
+  version: string;
+  activatedAt: string;
+}

package/src/cli/index.ts

@@ -10,6 +10,14 @@ import type { StartedVectorApp } from '../types';
 // Compatibility layer for both Node and Bun
 const args = typeof Bun !== 'undefined' ? Bun.argv.slice(2) : process.argv.slice(2);
 
+// Handle checkpoint subcommand early — it has its own arg format
+// and would conflict with the main parseArgs strict mode.
+if (args[0] === 'checkpoint') {
+  const { runCheckpointCli } = await import('../checkpoint/cli');
+  await runCheckpointCli(args.slice(1));
+  process.exit(0);
+}
+
 const { values, positionals } = parseArgs({
   args,
   options: {
@@ -224,8 +232,9 @@ switch (command) {
 Usage: vector [command] [options]
 
 Commands:
-  dev     Start development server (default)
-  start   Start production server
+  dev       Start development server (default)
+  start     Start production server
+  checkpoint  Manage versioned checkpoints (publish, list, rollback, remove)
 
 Options:
   -p, --port <port>      Port to listen on (default: 3000)

package/src/cli/option-resolution.ts

@@ -20,7 +20,11 @@ function parseAndValidatePort(value: unknown): number {
   return parsed;
 }
 
-export function resolvePort(configPort: number | null | undefined, hasPortOption: boolean, cliPort: string): number {
+export function resolvePort(
+  configPort: string | number | null | undefined,
+  hasPortOption: boolean,
+  cliPort: string
+): number {
   if (hasPortOption) {
     return parseAndValidatePort(cliPort);
   }

package/src/core/config-loader.ts

@@ -29,8 +29,9 @@ export class ConfigLoader<TTypes extends VectorTypes = DefaultVectorTypes> {
     if (existsSync(this.configPath)) {
       try {
         // Use explicit file:// URL to ensure correct resolution
+        // Append cache-busting query to force re-import on dev reload
         const userConfigPath = toFileUrl(this.configPath);
-        const userConfig = await import(userConfigPath);
+        const userConfig = await import(`${userConfigPath}?t=${Date.now()}`);
         this.config = userConfig.default || userConfig;
         this.configSource = 'user';
       } catch (error: any) {
@@ -57,7 +58,7 @@ export class ConfigLoader<TTypes extends VectorTypes = DefaultVectorTypes> {
 
     // Direct mapping - schemas are now the same (flat)
     if (this.config) {
-      config.port = this.config.port;
+      config.port = this.normalizePort(this.config.port);
       config.hostname = this.config.hostname;
       config.reusePort = this.config.reusePort;
       config.development = this.config.development;
@@ -68,6 +69,7 @@ export class ConfigLoader<TTypes extends VectorTypes = DefaultVectorTypes> {
       config.openapi = this.config.openapi;
       config.startup = this.config.startup;
       config.shutdown = this.config.shutdown;
+      config.checkpoint = this.config.checkpoint;
     }
 
     // Always auto-discover routes
@@ -103,6 +105,13 @@ export class ConfigLoader<TTypes extends VectorTypes = DefaultVectorTypes> {
     return config;
   }
 
+  private normalizePort(port: number | string | undefined): number | undefined {
+    if (port === undefined) {
+      return undefined;
+    }
+    return Number(port);
+  }
+
   async loadAuthHandler(): Promise<ProtectedHandler<TTypes> | null> {
     return this.config?.auth || null;
   }