@kb-labs/adapters 0.5.0

package/packages/adapters-qdrant/src/retry.ts

@@ -0,0 +1,204 @@
+/**
+ * @module @kb-labs/adapters-qdrant/retry
+ * Exponential-backoff retry logic for transient Qdrant errors.
+ *
+ * Retryable error codes / status codes:
+ *   - ECONNREFUSED  – Qdrant not yet reachable (startup, restart)
+ *   - ETIMEDOUT     – network or request timeout
+ *   - ECONNRESET    – connection reset by peer (proxy / load-balancer glitch)
+ *   - ENOTFOUND     – DNS hiccup (transient in cloud environments)
+ *   - HTTP 503      – Service Unavailable (Qdrant overloaded / restarting)
+ *   - HTTP 429      – Too Many Requests (rate-limited; also worth retrying)
+ *   - HTTP 502 / 504 – upstream gateway errors (common behind a proxy)
+ */
+
+/** Options for {@link withRetry}. */
+export interface RetryOptions {
+  /**
+   * Maximum number of *attempts* (first call + retries).
+   * @default 4
+   */
+  maxAttempts?: number;
+
+  /**
+   * Base delay in milliseconds between attempts.
+   * Actual delay = `baseDelayMs * 2^(attempt - 1)` + jitter.
+   * @default 200
+   */
+  baseDelayMs?: number;
+
+  /**
+   * Maximum delay cap in milliseconds (prevents runaway back-off).
+   * @default 10_000
+   */
+  maxDelayMs?: number;
+
+  /**
+   * Extra predicate called after built-in checks.
+   * Return `true` to treat the error as retryable.
+   */
+  isRetryable?: (error: unknown) => boolean;
+
+  /**
+   * Optional callback invoked before each retry sleep.
+   * Useful for logging / metrics.
+   */
+  onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+
+/** @internal The set of retryable Node.js `syscall` / `code` strings. */
+const RETRYABLE_CODES = new Set([
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EPIPE",
+  "ECONNABORTED",
+]);
+
+/** @internal HTTP status codes that are safe to retry. */
+const RETRYABLE_HTTP_STATUSES = new Set([429, 502, 503, 504]);
+
+/**
+ * Determine whether `error` represents a transient, retryable failure.
+ *
+ * Checks:
+ *  1. Node.js network error codes (`error.code`)
+ *  2. HTTP response status (`error.status`, `error.statusCode`,
+ *     `error.response?.status`)
+ *  3. Error message substrings as a last resort
+ */
+export function isTransientError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  // 1. Node.js network error codes
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code && RETRYABLE_CODES.has(code)) {
+    return true;
+  }
+
+  // 2. HTTP status codes  (Qdrant JS client surfaces these in different ways)
+  const anyErr = error as unknown as Record<string, unknown>;
+
+  const status =
+    (typeof anyErr["status"] === "number" ? anyErr["status"] : undefined) ??
+    (typeof anyErr["statusCode"] === "number"
+      ? anyErr["statusCode"]
+      : undefined) ??
+    (typeof (anyErr["response"] as Record<string, unknown> | undefined)?.[
+      "status"
+    ] === "number"
+      ? ((anyErr["response"] as Record<string, unknown>)["status"] as number)
+      : undefined);
+
+  if (typeof status === "number" && RETRYABLE_HTTP_STATUSES.has(status)) {
+    return true;
+  }
+
+  // 3. Message substrings (fallback for environments that don't expose codes)
+  const msg = error.message.toLowerCase();
+  if (
+    msg.includes("econnrefused") ||
+    msg.includes("etimedout") ||
+    msg.includes("econnreset") ||
+    msg.includes("service unavailable") ||
+    msg.includes("503")
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Sleep for `ms` milliseconds.
+ * @internal
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+/**
+ * Compute the delay before the next attempt using full-jitter exponential
+ * back-off: `random(0, min(cap, base * 2^attempt))`.
+ * @internal
+ */
+function computeDelay(
+  attempt: number,
+  baseDelayMs: number,
+  maxDelayMs: number,
+): number {
+  // attempt is 0-indexed here (0 = first retry after the initial failure)
+  const exponential = baseDelayMs * Math.pow(2, attempt);
+  const capped = Math.min(exponential, maxDelayMs);
+  // Full jitter: uniform in [0, capped]
+  return Math.floor(Math.random() * capped);
+}
+
+/**
+ * Wrap an async operation with exponential-backoff retry on transient errors.
+ *
+ * Only errors identified as transient (ECONNREFUSED, ETIMEDOUT, 503, etc.)
+ * are retried.  All other errors are re-thrown immediately.
+ *
+ * @param fn         The async operation to execute.
+ * @param options    Retry configuration.
+ * @returns          The resolved value of `fn`.
+ * @throws           The last error if all attempts are exhausted, or the
+ *                   first non-transient error encountered.
+ *
+ * @example
+ * ```ts
+ * const results = await withRetry(
+ *   () => this.client.search(this.collectionName, params),
+ *   { maxAttempts: 4, baseDelayMs: 200, maxDelayMs: 10_000 }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const maxAttempts = options.maxAttempts ?? 4;
+  const baseDelayMs = options.baseDelayMs ?? 200;
+  const maxDelayMs = options.maxDelayMs ?? 10_000;
+  const { isRetryable: extraIsRetryable, onRetry } = options;
+
+  if (maxAttempts < 1) {
+    throw new RangeError(`maxAttempts must be >= 1, got ${maxAttempts}`);
+  }
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      const retryable =
+        isTransientError(error) || (extraIsRetryable?.(error) ?? false);
+
+      // Non-transient error — rethrow immediately without retrying
+      if (!retryable) {
+        throw error;
+      }
+
+      // Last attempt exhausted — rethrow
+      if (attempt >= maxAttempts) {
+        break;
+      }
+
+      // Compute backoff delay (attempt - 1 = retry index)
+      const delayMs = computeDelay(attempt - 1, baseDelayMs, maxDelayMs);
+
+      onRetry?.(error, attempt, delayMs);
+
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}

package/packages/adapters-qdrant/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-qdrant/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-qdrant/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  dts: true,
+});

package/packages/adapters-redis/README.md

@@ -0,0 +1,159 @@
+# @kb-labs/adapters-redis
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+High-performance distributed cache adapter using Redis with TTL, patterns, and atomic operations.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `ICache` |
+| **Type** | `core` |
+| **Requires** | None |
+| **Category** | Cache |
+
+## Features
+
+- **TTL Support** - Automatic key expiration
+- **Pattern Operations** - Scan and delete by pattern
+- **Atomic Operations** - Increment, decrement, compare-and-set
+- **Key Prefixing** - Namespace isolation
+- **Connection Pooling** - Efficient connection management
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-redis
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "cache": "@kb-labs/adapters-redis"
+    },
+    "adapterOptions": {
+      "cache": {
+        "host": "localhost",
+        "port": 6379,
+        "keyPrefix": "kb:"
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | `"localhost"` | Redis server host |
+| `port` | `number` | `6379` | Redis server port |
+| `keyPrefix` | `string` | `"kb:"` | Prefix for all cache keys |
+| `password` | `string` | - | Redis password (optional) |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Set with TTL (60 seconds)
+await platform.cache.set('user:123', { name: 'John' }, 60000);
+
+// Get
+const user = await platform.cache.get<User>('user:123');
+
+// Delete
+await platform.cache.delete('user:123');
+
+// Clear all with pattern
+await platform.cache.deletePattern('user:*');
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-redis';
+
+const cache = createAdapter({
+  host: 'localhost',
+  port: 6379,
+  keyPrefix: 'test:'
+});
+
+await cache.set('key', 'value', 60000);
+const value = await cache.get('key');
+```
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'redis-cache',
+  name: 'Redis Cache',
+  version: '1.0.0',
+  implements: 'ICache',
+  capabilities: {
+    custom: {
+      ttl: true,
+      patterns: true,
+      atomic: true,
+    },
+  },
+}
+```
+
+## FAQ
+
+<details>
+<summary><strong>Q: How do I connect to Redis with authentication?</strong></summary>
+
+Add password to config:
+
+```json
+{
+  "adapterOptions": {
+    "cache": {
+      "host": "redis.example.com",
+      "port": 6379,
+      "password": "your-password"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Q: How do I use Redis Cluster?</strong></summary>
+
+For cluster mode, use connection string format:
+
+```json
+{
+  "adapterOptions": {
+    "cache": {
+      "url": "redis://node1:6379,node2:6379,node3:6379"
+    }
+  }
+}
+```
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-eventbus-cache` | Event bus using cache backend |
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-redis/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/adapters-redis/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kb-labs/adapters-redis",
+  "version": "0.5.0",
+  "description": "Redis adapter implementing ICache interface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "ioredis": "^5.4.0"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-redis/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * @module @kb-labs/adapters-redis
+ * Redis adapter implementing ICache interface.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@kb-labs/adapters-redis';
+ *
+ * const cache = createAdapter({
+ *   host: 'localhost',
+ *   port: 6379,
+ * });
+ *
+ * await cache.set('user:123', { name: 'Alice' }, 60000); // TTL 60s
+ * const user = await cache.get('user:123');
+ * await cache.delete('user:123');
+ * await cache.clear('user:*');
+ * ```
+ */
+
+import Redis, { type RedisOptions } from "ioredis";
+import type { ICache } from "@kb-labs/core-platform";
+
+// Re-export manifest
+export { manifest } from "./manifest.js";
+
+/**
+ * Configuration for Redis cache adapter.
+ */
+export interface RedisCacheConfig extends RedisOptions {
+  /** Redis host (default: 'localhost') */
+  host?: string;
+  /** Redis port (default: 6379) */
+  port?: number;
+  /** Key prefix for all cache keys (default: 'kb:') */
+  keyPrefix?: string;
+}
+
+/**
+ * Redis implementation of ICache interface.
+ */
+export class RedisCacheAdapter implements ICache {
+  private client: Redis;
+  private keyPrefix: string;
+
+  constructor(config: RedisCacheConfig = {}) {
+    this.keyPrefix = config.keyPrefix ?? "kb:";
+
+    this.client = new Redis({
+      host: config.host ?? "localhost",
+      port: config.port ?? 6379,
+      ...config,
+      keyPrefix: this.keyPrefix,
+    });
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const value = await this.client.get(key);
+    if (value === null) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      // If not JSON, return as-is (cast to T)
+      return value as T;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+    const serialized = JSON.stringify(value);
+
+    if (ttl !== undefined) {
+      // TTL in milliseconds, Redis uses seconds
+      await this.client.setex(key, Math.ceil(ttl / 1000), serialized);
+    } else {
+      await this.client.set(key, serialized);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+
+  async clear(pattern?: string): Promise<void> {
+    if (!pattern) {
+      // Clear all keys with our prefix
+      await this.client.flushdb();
+      return;
+    }
+
+    // Find keys matching pattern
+    const fullPattern = `${this.keyPrefix}${pattern}`;
+    const keys = await this.client.keys(fullPattern);
+
+    if (keys.length > 0) {
+      // Remove prefix before deleting (ioredis adds it automatically)
+      const keysWithoutPrefix = keys.map((k) => k.slice(this.keyPrefix.length));
+      await this.client.del(...keysWithoutPrefix);
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // Sorted Set Operations
+  // ═══════════════════════════════════════════════════════════════════════
+
+  async zadd(key: string, score: number, member: string): Promise<void> {
+    await this.client.zadd(key, score, member);
+  }
+
+  async zrangebyscore(
+    key: string,
+    min: number,
+    max: number,
+  ): Promise<string[]> {
+    return this.client.zrangebyscore(key, min, max);
+  }
+
+  async zrem(key: string, member: string): Promise<void> {
+    await this.client.zrem(key, member);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // Atomic Operations
+  // ═══════════════════════════════════════════════════════════════════════
+
+  async setIfNotExists<T>(
+    key: string,
+    value: T,
+    ttl?: number,
+  ): Promise<boolean> {
+    const serialized = JSON.stringify(value);
+
+    if (ttl !== undefined) {
+      // SET key value PX milliseconds NX
+      const result = await this.client.set(key, serialized, "PX", ttl, "NX");
+      return result === "OK";
+    } else {
+      // SET key value NX (no TTL)
+      const result = await this.client.set(key, serialized, "NX");
+      return result === "OK";
+    }
+  }
+
+  /**
+   * Close Redis connection.
+   * Call this on app shutdown.
+   */
+  async disconnect(): Promise<void> {
+    await this.client.quit();
+  }
+}
+
+/**
+ * Create Redis cache adapter.
+ * This is the factory function called by initPlatform() when loading adapters.
+ */
+export function createAdapter(config?: RedisCacheConfig): RedisCacheAdapter {
+  return new RedisCacheAdapter(config);
+}
+
+// Default export for direct import
+export default createAdapter;

package/packages/adapters-redis/src/manifest.ts

@@ -0,0 +1,49 @@
+/**
+ * @module @kb-labs/adapters-redis/manifest
+ * Adapter manifest for Redis cache.
+ */
+
+import type { AdapterManifest } from "@kb-labs/core-platform";
+
+/**
+ * Adapter manifest for Redis cache.
+ */
+export const manifest: AdapterManifest = {
+  manifestVersion: "1.0.0",
+  id: "redis-cache",
+  name: "Redis Cache",
+  version: "1.0.0",
+  description: "High-performance distributed cache using Redis",
+  author: "KB Labs Team",
+  license: "KBPL-1.1",
+  type: "core",
+  implements: "ICache",
+  capabilities: {
+    custom: {
+      ttl: true,
+      patterns: true,
+      atomic: true,
+    },
+  },
+  configSchema: {
+    host: {
+      type: "string",
+      default: "localhost",
+      description: "Redis server host",
+    },
+    port: {
+      type: "number",
+      default: 6379,
+      description: "Redis server port",
+    },
+    keyPrefix: {
+      type: "string",
+      default: "kb:",
+      description: "Prefix for all cache keys",
+    },
+    password: {
+      type: "string",
+      description: "Redis password (optional)",
+    },
+  },
+};

package/packages/adapters-redis/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}