@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/events/circuit-breaker.d.ts

@@ -0,0 +1,33 @@
+import type { EventRouterConfig } from './types.js';
+/**
+ * Circuit breaker for event loop detection and per-workflow rate limiting.
+ *
+ * Two-layer protection:
+ * 1. Chain depth: Rejects events exceeding configurable max chain depth.
+ * 2. Rate limiting: Sliding-window per-workflow rate limiter.
+ */
+export declare class EventCircuitBreaker {
+    private readonly config;
+    private rateLimiter;
+    constructor(config: EventRouterConfig);
+    /**
+     * Check if the current chain depth is within limits.
+     */
+    checkChainDepth(currentDepth: number): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Check if a workflow is within its per-minute rate limit.
+     * Uses a sliding window of 60 seconds.
+     */
+    checkRateLimit(workflowKey: string): {
+        allowed: boolean;
+        retryAfterMs?: number;
+    };
+    /**
+     * Clear all rate limit state (for testing).
+     */
+    reset(): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/events/event-emitter.d.ts

@@ -0,0 +1,55 @@
+import type { EventRouter } from './event-router.js';
+/**
+ * Input data for emitting a workflow_complete system event.
+ */
+export interface WorkflowCompleteData {
+    routingKey: string;
+    repo: string;
+    workflowName: string;
+    runId: string;
+    status: string;
+    conclusion: string;
+    duration: number;
+    jobResults: Array<{
+        name: string;
+        status: string;
+    }>;
+}
+/**
+ * Input data for emitting a job_complete system event.
+ */
+export interface JobCompleteData {
+    routingKey: string;
+    repo: string;
+    workflowName: string;
+    jobName: string;
+    runId: string;
+    jobId: string;
+    status: string;
+    duration: number;
+    stepResults: Array<{
+        name: string;
+        status: string;
+    }>;
+}
+/**
+ * EventEmitter automatically generates system events when workflows and jobs complete.
+ *
+ * System events are root-level (chainDepth: 0) since they originate from the
+ * orchestrator, not from a chain of events.
+ */
+export declare class EventEmitter {
+    private readonly router;
+    constructor(router: EventRouter);
+    /**
+     * Emit a __workflow_complete system event with rich metadata.
+     * Returns the event ID as delivery receipt.
+     */
+    emitWorkflowComplete(data: WorkflowCompleteData): Promise<string>;
+    /**
+     * Emit a __job_complete system event with rich metadata.
+     * Returns the event ID as delivery receipt.
+     */
+    emitJobComplete(data: JobCompleteData): Promise<string>;
+}
+//# sourceMappingURL=event-emitter.d.ts.map

package/dist/events/event-retry-scanner.d.ts

@@ -0,0 +1,52 @@
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { EventStore } from './event-store.js';
+import type { EventRouterConfig } from './types.js';
+interface EventRetryScannerOptions {
+    db: Kysely<Database>;
+    eventStore: EventStore;
+    config: EventRouterConfig;
+}
+/**
+ * Leader-only periodic scanner that closes two gaps in event delivery:
+ *
+ *  1. Retries: events whose `next_retry_at <= NOW()` are re-published via
+ *     `pg_notify('kici_event_channel', id)` so any healthy orchestrator
+ *     picks them up via the normal `LISTEN/NOTIFY` path. The receiver's
+ *     `tryLeaseForProcessing` ensures only one node actually dispatches.
+ *
+ *  2. Lease expiry: events whose `claimed_at` is older than
+ *     `leaseDurationMs` belong to a node that crashed (or hung) before
+ *     finalising the dispatch. The scanner releases the lease (clears
+ *     `claimed_at`, sets `next_retry_at = NOW()`) and re-publishes
+ *     `pg_notify`. This is the visible signal — via
+ *     `kici_orch_event_lease_expirations_total` — that a node died
+ *     mid-dispatch.
+ *
+ * The scanner also refreshes the `kici_orch_event_dlq_depth` gauge so
+ * operators can alert on DLQ growth.
+ *
+ * Modeled on `CronScheduler`: leader-only, started/stopped via Raft
+ * leadership callbacks, single timer cleared on `stop()`.
+ */
+export declare class EventRetryScanner {
+    private readonly db;
+    private readonly eventStore;
+    private readonly config;
+    private timer;
+    private isLeader;
+    constructor(options: EventRetryScannerOptions);
+    onBecomeLeader(): void;
+    onLoseLeadership(): void;
+    stop(): void;
+    /**
+     * One scanner tick. Public for tests; not on the hot path otherwise.
+     */
+    tick(): Promise<void>;
+    private processExpiredLeases;
+    private processDueRetries;
+    private refreshDlqDepth;
+    private publishNotify;
+}
+export {};
+//# sourceMappingURL=event-retry-scanner.d.ts.map

package/dist/events/event-router.d.ts

@@ -0,0 +1,183 @@
+import type pg from 'pg';
+import { type Kysely, type Transaction } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { LockFile, WorkflowDecision } from '@kici-dev/engine';
+import type { EventStore } from './event-store.js';
+import type { EventCircuitBreaker } from './circuit-breaker.js';
+import type { TrustStore } from './trust-store.js';
+import type { RegistrationIndex } from '../registration/registration-index.js';
+import type { EventRouterConfig, StoredEvent } from './types.js';
+/**
+ * Input for emitting an internal event.
+ */
+export interface EmitEventInput {
+    eventName: string;
+    payload: Record<string, unknown>;
+    sourceRepo?: string;
+    sourceRoutingKey?: string;
+    sourceRunId?: string;
+    sourceJobId?: string;
+    /** Optional cross-repo targeting: deliver only to registrations matching these repos */
+    target?: {
+        repos?: string[];
+    };
+    chainDepth?: number;
+}
+/**
+ * Context about the registration that matched an event.
+ */
+export interface EventMatchContext {
+    /** Routing key (e.g., "github:42") for provider resolution */
+    routingKey: string;
+    /** Repository identifier (e.g., "owner/repo") */
+    repoIdentifier: string;
+    /** Provider-specific credentials captured at registration time */
+    providerContext: Record<string, unknown>;
+}
+export interface EventRouterOptions {
+    db: Kysely<Database>;
+    pool: pg.Pool;
+    eventStore: EventStore;
+    circuitBreaker: EventCircuitBreaker;
+    trustStore: TrustStore;
+    config: EventRouterConfig;
+    onEventMatched: (event: StoredEvent, lockFile: LockFile, matchedWorkflows: WorkflowDecision[], context?: EventMatchContext) => Promise<void>;
+    /** Registration index for DB-backed subscription matching. Events match against persistent registrations. */
+    registrationIndex: RegistrationIndex;
+    /** Stable identifier for this orchestrator process — written into `kici_events.claimed_by` for diagnostics. */
+    nodeId: string;
+}
+/**
+ * EventRouter delivers internal events to matching workflows via PostgreSQL LISTEN/NOTIFY.
+ *
+ * Follows the WebhookSecretManager pattern: raw pg.PoolClient for LISTEN,
+ * Kysely for queries.
+ *
+ * On start, performs a catch-up scan for events missed during downtime.
+ * On notification, leases the event from DB, matches against registered
+ * workflows via the RegistrationIndex, and calls onEventMatched for each
+ * match. Failures schedule a retry via `recordDispatchFailure`; events that
+ * exhaust `maxDispatchAttempts` are moved to the DLQ via `markDlq`.
+ */
+export declare class EventRouter {
+    private readonly db;
+    private readonly pool;
+    private readonly eventStore;
+    private readonly circuitBreaker;
+    private readonly trustStore;
+    private readonly config;
+    private readonly onEventMatched;
+    private readonly registrationIndex;
+    private readonly nodeId;
+    private client;
+    private lastProcessedEventId;
+    constructor(options: EventRouterOptions);
+    /**
+     * Start listening for events via PostgreSQL LISTEN/NOTIFY.
+     * Runs catch-up on start to process events missed during downtime.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop listening and release the dedicated pg client.
+     */
+    stop(): Promise<void>;
+    /**
+     * Emit an internal event using the default DB handle.
+     *
+     * Wraps `emitInTx` in its own transaction. Callers that need to combine
+     * the emit with other transactional work (cron-fire being the canonical
+     * case) should call `emitInTx` directly with their own tx so all writes
+     * commit or roll back together.
+     */
+    emit(event: EmitEventInput): Promise<string>;
+    /**
+     * Emit an internal event inside a caller-provided transaction.
+     *
+     * Circuit-breaker checks (chain depth + rate limit) run BEFORE the
+     * transaction so they fail fast without burning DB roundtrips. The
+     * `kici_events` insert and the `pg_notify` are issued on the supplied
+     * `tx` so they only become visible (and the notification is only
+     * delivered) on commit. Postgres queues NOTIFYs issued inside a
+     * transaction and releases them at COMMIT; if the tx rolls back, no
+     * listener is woken — exactly what we need to make cron-fire atomic.
+     */
+    emitInTx(event: EmitEventInput, tx: Transaction<Database>): Promise<string>;
+    /**
+     * Handle a LISTEN/NOTIFY notification for a new event.
+     *
+     * Lease-based dispatch (replaces the previous "flip processed=true upfront"
+     * pattern that silently lost events when dispatch threw):
+     *
+     *  1. Take a dispatch lease (claimed_at + claimed_by, attempts++).
+     *     Fails fast if the event is already processed, in DLQ, or held by a
+     *     fresh lease on another node.
+     *  2. Run dispatch. On success: markProcessed (clears lease, processed=true).
+     *  3. On failure: either schedule a retry (recordDispatchFailure → leader
+     *     scanner re-publishes pg_notify when next_retry_at elapses) or move
+     *     to the DLQ (markDlq) when attempts exceed maxDispatchAttempts.
+     *
+     * If the dispatching node crashes between lease and finalisation, the
+     * leader-only retry scanner releases the lease after leaseDurationMs and
+     * re-publishes pg_notify so a healthy node can re-dispatch.
+     */
+    private onNotification;
+    /**
+     * Run dispatch for a leased event and record the outcome (processed,
+     * retry, or DLQ). Used by both the live notification handler and the
+     * catch-up loop so the failure semantics stay identical.
+     */
+    private dispatchAndRecord;
+    /**
+     * Match an event against all registered workflows and dispatch matches.
+     *
+     * Looks up registrations by trigger type via the RegistrationIndex,
+     * builds per-registration lock files, and runs trigger matching against them.
+     *
+     * Errors propagate so the lease wrapper (`dispatchAndRecord`) can either
+     * schedule a retry or move the event to the DLQ. Swallowing the error
+     * here would silently lose the event — exactly the failure mode the
+     * lease pattern fixes.
+     */
+    private processSubscriptions;
+    /**
+     * Map a stored event to a trigger type string for RegistrationIndex lookup.
+     *
+     * System events (__workflow_complete, __job_complete) map to their type without __ prefix.
+     * Custom events map to 'kici_event'.
+     */
+    private eventToTriggerType;
+    /**
+     * Build a SimulatedEvent from a StoredEvent for trigger matching.
+     *
+     * System events (__workflow_complete, __job_complete) map their type by
+     * stripping the __ prefix and pass the payload through directly (the
+     * matcher checks payload.workflowName, payload.status, etc.).
+     *
+     * Custom events use type 'kici_event'. The matcher reads eventName and
+     * the user payload from event.payload.eventName / event.payload.payload,
+     * so we wrap the stored event's metadata into the expected structure.
+     */
+    private buildSimulatedEvent;
+    /**
+     * Catch-up: process unprocessed events missed during downtime.
+     *
+     * Uses lease-based dispatch identical to the live path, so a catch-up
+     * dispatch failure schedules a retry via the leader-only scanner instead
+     * of being silently dropped.
+     */
+    private catchUp;
+}
+/**
+ * Compute the next retry timestamp using exponential backoff with full
+ * jitter. `attempts` is the count AFTER the most recent failed attempt.
+ *
+ *   target = min(maxBackoffMs, baseBackoffMs * 2^(attempts - 1))
+ *   actual = random in [0, target]
+ *
+ * Full jitter (vs. equal jitter or no jitter) gives the best balance
+ * between worst-case retry concentration and average latency, per the AWS
+ * "Exponential backoff and jitter" article. baseBackoffMs and
+ * maxBackoffMs come from EventRouterConfig so tests can shrink them.
+ */
+export declare function computeNextRetryAt(attempts: number, baseBackoffMs: number, maxBackoffMs: number, now?: () => number): Date;
+//# sourceMappingURL=event-router.d.ts.map

package/dist/events/event-store.d.ts

@@ -0,0 +1,157 @@
+import { type Kysely, type Transaction } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { DlqReason, EventRouterConfig, StoredEvent } from './types.js';
+/** Either a Kysely DB handle or an active transaction. */
+export type DbExecutor = Kysely<Database> | Transaction<Database>;
+/**
+ * Input shape for writing a new event. Excludes columns the DB fills in
+ * itself (id, processed, created_at, attempts, claimed_*, last_error,
+ * next_retry_at, dlq_*).
+ */
+export interface NewEventInput {
+    eventName: string;
+    payload: Record<string, unknown>;
+    sourceRepo?: string;
+    sourceRoutingKey?: string;
+    sourceRunId?: string;
+    sourceJobId?: string;
+    targetRepos?: string[];
+    chainDepth: number;
+    expiresAt: Date;
+}
+/**
+ * Persists and queries internal events (system + custom).
+ *
+ * Provides:
+ *  - TTL-based cleanup for expired non-DLQ events.
+ *  - Lease-based dispatch claim with bounded retries (replaces the prior
+ *    "flip processed=true upfront" pattern that silently lost events when
+ *    dispatch threw).
+ *  - DLQ helpers for surfacing events that exhausted retries.
+ */
+export declare class EventStore {
+    private readonly db;
+    private readonly config;
+    private cleanupTimer;
+    constructor(db: Kysely<Database>, config: EventRouterConfig);
+    /**
+     * Expose the underlying Kysely handle for callers that need to issue
+     * `pg_notify` outside of EventStore (e.g. the admin DLQ retry route, which
+     * re-publishes after `resetFromDlq` so a healthy node picks the event up
+     * before the next retry-scanner tick).
+     */
+    getDb(): Kysely<Database>;
+    /**
+     * Write a new event to the store using the default DB handle.
+     * Computes expires_at from the configured TTL.
+     * Returns the generated event ID.
+     */
+    write(event: NewEventInput): Promise<string>;
+    /**
+     * Write a new event using a caller-provided executor (typically a Kysely
+     * Transaction). Used by `EventRouter.emitInTx` to atomically combine the
+     * insert with other transactional work (e.g. cron `tryClaimFire`).
+     */
+    writeWith(event: NewEventInput, executor: DbExecutor): Promise<string>;
+    /**
+     * Retrieve a single event by ID.
+     */
+    getById(id: string): Promise<StoredEvent | null>;
+    /**
+     * Get unprocessed events for catch-up on reconnect.
+     * If sinceId is null, returns all unprocessed events.
+     * Ordered by created_at ASC. Excludes DLQ rows.
+     */
+    getUnprocessedSince(sinceId: string | null, limit?: number): Promise<StoredEvent[]>;
+    /**
+     * Mark an event as fully processed. Called after a successful dispatch.
+     * Clears any prior lease so the row is unambiguously terminal.
+     */
+    markProcessed(id: string): Promise<void>;
+    /**
+     * Atomically take a dispatch lease on an event. Replaces the previous
+     * "flip processed=true upfront" pattern that silently lost events when
+     * dispatch threw after the flip.
+     *
+     * The UPDATE succeeds when:
+     *  - the event is not yet processed and not in DLQ, AND
+     *  - either no lease is held, OR the existing lease has expired.
+     *
+     * On success: sets `claimed_at = NOW()`, `claimed_by = $leaseHolder`,
+     * increments `attempts`. The caller must subsequently call `markProcessed`
+     * (success), `recordDispatchFailure` (failure with retry), or `markDlq`
+     * (terminal failure) — otherwise the lease times out after
+     * `leaseDurationMs` and the leader-only retry scanner releases it.
+     *
+     * Returns the leased event row, or null if the event was already
+     * processed/leased/DLQ'd.
+     */
+    tryLeaseForProcessing(id: string, leaseHolder: string): Promise<StoredEvent | null>;
+    /**
+     * Record a failed dispatch attempt. Releases the lease, stores the
+     * (truncated) error, and schedules the next retry. The leader-only
+     * retry scanner will re-publish `pg_notify` for this event when
+     * `next_retry_at <= NOW()`.
+     */
+    recordDispatchFailure(id: string, errorMessage: string, nextRetryAt: Date): Promise<void>;
+    /**
+     * Mark an event as DLQ. Sets `processed=true` so it stops being eligible
+     * for retry, records `dlq_at` + `dlq_reason`, and preserves `last_error`
+     * (overwritten if a fresh error message is provided).
+     */
+    markDlq(id: string, reason: DlqReason, errorMessage?: string): Promise<void>;
+    /**
+     * Find events whose `next_retry_at` is due. The leader-only retry scanner
+     * uses this to know which events to re-publish via `pg_notify`.
+     */
+    findEventsDueForRetry(limit: number): Promise<StoredEvent[]>;
+    /**
+     * Find events whose lease has expired. The leader-only scanner releases
+     * these (clears `claimed_at` + sets `next_retry_at = NOW()`) and then
+     * re-publishes `pg_notify` so a healthy node picks them up.
+     */
+    findExpiredLeases(limit: number): Promise<StoredEvent[]>;
+    /**
+     * Release an expired lease so the event is once again eligible for
+     * `tryLeaseForProcessing`. Used by the retry scanner together with a
+     * `pg_notify` re-publication.
+     */
+    releaseExpiredLease(id: string): Promise<void>;
+    /**
+     * List events currently in the DLQ. Most recent first. Used by the
+     * dashboard admin DLQ page.
+     */
+    listDlq(limit: number, beforeDlqAt?: Date): Promise<StoredEvent[]>;
+    /**
+     * Count events currently in the DLQ. Used by the dashboard summary row
+     * and the `kici_orch_event_dlq_depth` gauge.
+     */
+    countDlq(): Promise<number>;
+    /**
+     * Reset a DLQ event so it gets retried on the next scanner tick. Used by
+     * the dashboard "Retry" action.
+     */
+    resetFromDlq(id: string): Promise<boolean>;
+    /**
+     * Permanently delete a DLQ event. Used by the dashboard "Discard" action.
+     */
+    deleteDlq(id: string): Promise<boolean>;
+    /**
+     * Delete expired events. Returns the count of deleted rows. DLQ rows are
+     * preserved so operators have time to triage them.
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Start periodic cleanup using setInterval.
+     */
+    startCleanupTimer(): void;
+    /**
+     * Stop periodic cleanup.
+     */
+    stopCleanupTimer(): void;
+    /**
+     * Convert a DB row to a StoredEvent.
+     */
+    private rowToStoredEvent;
+}
+//# sourceMappingURL=event-store.d.ts.map

package/dist/events/trust-store.d.ts

@@ -0,0 +1,54 @@
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * Trust entry representing a cross-repo trust relationship.
+ */
+interface TrustEntry {
+    id: string;
+    sourceRepo: string;
+    sourceRoutingKey: string;
+    targetRepo: string;
+    targetRoutingKey: string;
+    allowedEvents: string[] | null;
+    enabled: boolean;
+}
+/**
+ * TrustStore enforces bidirectional trust for cross-repo event delivery.
+ *
+ * Same-repo events (same routing key) are always trusted without a DB lookup.
+ * Cross-repo events require an explicit enabled row in the cross_repo_trust table.
+ * Glob-based event filtering is supported via the allowed_events column.
+ */
+export declare class TrustStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Check whether event delivery from source to target is trusted.
+     *
+     * Same-routing-key events bypass the DB lookup entirely.
+     * Cross-repo events require an enabled row with matching event name.
+     */
+    isTrusted(sourceRepo: string, sourceRoutingKey: string, targetRepo: string, targetRoutingKey: string, eventName: string): Promise<boolean>;
+    /**
+     * Add a trust relationship between source and target.
+     * Uses ON CONFLICT DO NOTHING for idempotent inserts.
+     * Returns the trust entry ID.
+     */
+    addTrust(source: {
+        repo: string;
+        routingKey: string;
+    }, target: {
+        repo: string;
+        routingKey: string;
+    }, allowedEvents?: string[]): Promise<string>;
+    /**
+     * Remove a trust relationship by ID.
+     */
+    removeTrust(id: string): Promise<void>;
+    /**
+     * List all trust relationships for a routing key (as source or target).
+     */
+    listTrust(routingKey: string): Promise<TrustEntry[]>;
+}
+export {};
+//# sourceMappingURL=trust-store.d.ts.map

package/dist/events/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Event routing configuration and types.
+ */
+/**
+ * Configuration for the event routing system.
+ */
+export interface EventRouterConfig {
+    /** Maximum allowed chain depth before circuit breaker trips (default: 10) */
+    maxChainDepth: number;
+    /** Maximum event emissions per workflow per minute (default: 100) */
+    rateLimitPerWorkflowPerMinute: number;
+    /** TTL for persisted events in seconds (default: 604800 = 7 days) */
+    eventTtlSeconds: number;
+    /** Interval between cleanup runs in milliseconds (default: 3600000 = 1 hour) */
+    cleanupIntervalMs: number;
+    /** Max dispatch attempts before an event is moved to the DLQ (default: 5) */
+    maxDispatchAttempts: number;
+    /** How long a dispatch lease is valid before another node may steal it (default: 60_000) */
+    leaseDurationMs: number;
+    /** Base backoff for exponential retry, with full jitter (default: 5_000) */
+    retryBaseBackoffMs: number;
+    /** Maximum backoff cap (default: 300_000 = 5 min) */
+    retryMaxBackoffMs: number;
+    /** Interval at which the leader-only retry scanner ticks (default: 10_000) */
+    retryScanIntervalMs: number;
+}
+/**
+ * Reason an event landed in the DLQ.
+ */
+export type DlqReason = 'exhausted_retries' | 'non_retryable';
+/**
+ * A stored internal event (matches DB row shape but with JS types).
+ */
+export interface StoredEvent {
+    id: string;
+    eventName: string;
+    payload: Record<string, unknown>;
+    sourceRepo?: string;
+    sourceRoutingKey?: string;
+    sourceRunId?: string;
+    sourceJobId?: string;
+    /** Optional target repos for cross-repo event targeting */
+    targetRepos?: string[];
+    chainDepth: number;
+    processed: boolean;
+    createdAt: Date;
+    expiresAt: Date;
+    /** Lease + retry + DLQ fields (added by migration 014) */
+    claimedAt: Date | null;
+    claimedBy: string | null;
+    attempts: number;
+    lastError: string | null;
+    nextRetryAt: Date | null;
+    dlqAt: Date | null;
+    dlqReason: DlqReason | null;
+}
+/**
+ * Default event router configuration.
+ */
+export declare const DEFAULT_EVENT_ROUTER_CONFIG: EventRouterConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/helpers/ip-extraction.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared IP extraction helper with trusted proxy + CIDR support.
+ *
+ * Used by app.ts to extract the real client IP from Hono context,
+ * respecting proxy headers only when the direct connection comes
+ * from a configured trusted proxy.
+ */
+import type { Context } from 'hono';
+import type { ConnInfo } from 'hono/conninfo';
+/**
+ * Normalize an IP address by stripping the IPv6-mapped IPv4 prefix.
+ * E.g., '::ffff:127.0.0.1' -> '127.0.0.1'
+ */
+export declare function normalizeIp(ip: string): string;
+/**
+ * Check if a socket IP is a trusted proxy.
+ * Supports exact IP matches and CIDR ranges.
+ * IPv6-mapped IPv4 addresses are normalized before comparison.
+ */
+export declare function isTrustedProxy(socketIp: string, trustedProxies: string[]): boolean;
+/**
+ * Extract the real remote IP from a Hono request context.
+ *
+ * - If the direct socket is a trusted proxy, reads X-Real-IP or X-Forwarded-For
+ * - Otherwise, returns the socket IP directly (ignoring proxy headers)
+ * - Returns 'unknown' if socket address is not available
+ */
+export declare function extractRemoteIp(c: Context, connInfo: ConnInfo, trustedProxies: string[]): string;
+//# sourceMappingURL=ip-extraction.d.ts.map

package/dist/helpers/rate-limiter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sliding-window rate limiter.
+ *
+ * Tracks timestamps of recent events per key and rejects new events
+ * once the count within the window exceeds the configured maximum.
+ */
+export declare class SlidingWindowRateLimiter {
+    private readonly maxPerWindow;
+    private readonly windowMs;
+    private state;
+    constructor(maxPerWindow: number, windowMs?: number);
+    /**
+     * Check if a new event is allowed for the given key.
+     * @param key - The rate limit bucket key.
+     * @param maxOverride - Per-call limit override (uses constructor default if omitted).
+     */
+    check(key: string, maxOverride?: number): {
+        allowed: boolean;
+        retryAfterMs?: number;
+    };
+    reset(): void;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { CacheStorage, CacheStorageConfig, CacheMetadata } from './storage/types.js';
+export { S3CacheStorage, type S3CacheStorageOptions } from './storage/s3.js';
+export { createCacheStorage } from './storage/index.js';
+export { SourceCache } from './cache/source-cache.js';
+export { DepCache } from './cache/dep-cache.js';
+export { PeerCredentialStore, createPeerCredentialStoreFromUrl, type PeerCredential, } from './cluster/peer-credentials.js';
+//# sourceMappingURL=index.d.ts.map