@docker-harpoon/core 0.1.4 → 0.1.5

package/dist/services/DockerClient.js

@@ -0,0 +1,220 @@
+/**
+ * DockerClient Service
+ *
+ * Provides a typed interface to Docker operations using Effect.
+ * This service wraps dockerode and converts all operations to Effect-based APIs.
+ */
+import { Context, Effect, Layer } from 'effect';
+import Docker from 'dockerode';
+import { existsSync } from 'fs';
+import { homedir, platform } from 'os';
+import { HarpoonConfig } from './HarpoonConfig';
+import { DockerConnectionError, wrapAsDockerError, isTransientError, } from './DockerErrors';
+import { DockerRateLimiter, DockerRateLimiterLive, dockerRetrySchedule } from './DockerRateLimiter';
+/**
+ * DockerClient service tag for dependency injection.
+ */
+export class DockerClient extends Context.Tag('@harpoon/DockerClient')() {
+}
+/**
+ * Detect Docker socket path for the current platform.
+ */
+function detectDockerSocket() {
+    const candidates = [
+        '/var/run/docker.sock',
+        `${homedir()}/.docker/run/docker.sock`,
+        // Colima on macOS
+        `${homedir()}/.colima/default/docker.sock`,
+    ];
+    for (const path of candidates) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    // Windows uses named pipes, let dockerode handle it
+    if (platform() === 'win32') {
+        return '//./pipe/docker_engine';
+    }
+    // Default fallback
+    return '/var/run/docker.sock';
+}
+/**
+ * Helper to add retry logic for transient errors.
+ */
+const withRetryOnTransient = (effect) => effect.pipe(Effect.retry({
+    schedule: dockerRetrySchedule,
+    while: (error) => isTransientError(error),
+}));
+/**
+ * Live implementation of DockerClient.
+ *
+ * Creates a connection to Docker and verifies it on startup.
+ * Requires HarpoonConfig and DockerRateLimiter to be provided.
+ *
+ * All Docker API operations are:
+ * - Rate limited via semaphore
+ * - Retried on transient errors with exponential backoff
+ */
+export const DockerClientLive = Layer.scoped(DockerClient, Effect.gen(function* () {
+    const config = yield* HarpoonConfig;
+    const rateLimiter = yield* DockerRateLimiter;
+    // Determine socket path
+    const socketPath = config.dockerSocket ?? detectDockerSocket();
+    // Create Docker client
+    const docker = new Docker({ socketPath });
+    // Verify connection on startup (with retry for transient errors)
+    yield* Effect.tryPromise({
+        try: () => docker.ping(),
+        catch: (e) => new DockerConnectionError(`Failed to connect to Docker daemon`, {
+            socketPath,
+            cause: e,
+        }),
+    }).pipe(withRetryOnTransient);
+    yield* Effect.logDebug('Connected to Docker daemon').pipe(Effect.annotateLogs({ socketPath }));
+    // Helper to wrap operations with rate limiting and retry
+    const withRateLimitAndRetry = (effect) => rateLimiter.withPermit(withRetryOnTransient(effect));
+    // Create the service implementation
+    const service = {
+        _tag: 'DockerClient',
+        client: docker,
+        ping: () => rateLimiter.withPermit(Effect.tryPromise({
+            try: () => docker.ping(),
+            catch: (e) => new DockerConnectionError(`Docker ping failed`, {
+                socketPath,
+                cause: e,
+            }),
+        }).pipe(Effect.asVoid)),
+        version: () => withRateLimitAndRetry(Effect.tryPromise({
+            try: () => docker.version(),
+            catch: (e) => wrapAsDockerError('version', e),
+        })),
+        listContainers: (options) => withRateLimitAndRetry(Effect.tryPromise({
+            try: () => docker.listContainers(options),
+            catch: (e) => wrapAsDockerError('listContainers', e),
+        })),
+        getContainer: (id) => docker.getContainer(id),
+        createContainer: (options) => withRateLimitAndRetry(Effect.tryPromise({
+            try: () => docker.createContainer(options),
+            catch: (e) => wrapAsDockerError('createContainer', e),
+        })),
+        listNetworks: (options) => withRateLimitAndRetry(Effect.tryPromise({
+            try: () => docker.listNetworks(options),
+            catch: (e) => wrapAsDockerError('listNetworks', e),
+        })),
+        getNetwork: (id) => docker.getNetwork(id),
+        createNetwork: (options) => withRateLimitAndRetry(Effect.tryPromise({
+            try: () => docker.createNetwork(options),
+            catch: (e) => wrapAsDockerError('createNetwork', e),
+        })),
+        getImage: (name) => docker.getImage(name),
+        listImages: () => withRateLimitAndRetry(Effect.tryPromise({
+            try: () => docker.listImages(),
+            catch: (e) => wrapAsDockerError('listImages', e),
+        })),
+        pullImage: (name, options) => 
+        // Pull uses multiple permits (2) as it's a heavier operation
+        rateLimiter.withPermits(2)(withRetryOnTransient(Effect.tryPromise({
+            try: async () => {
+                await new Promise((resolve, reject) => {
+                    docker.pull(name, options ?? {}, (err, stream) => {
+                        if (err || !stream) {
+                            reject(err ?? new Error('No stream returned from pull'));
+                            return;
+                        }
+                        // Follow pull progress to completion
+                        docker.modem.followProgress(stream, (followErr) => {
+                            if (followErr)
+                                reject(followErr);
+                            else
+                                resolve();
+                        });
+                    });
+                });
+            },
+            catch: (e) => wrapAsDockerError('pullImage', e),
+        }))),
+    };
+    return service;
+})).pipe(Layer.provide(DockerRateLimiterLive));
+/**
+ * Create a mock container for testing.
+ */
+const createMockContainer = (id) => ({
+    id,
+    start: () => Promise.resolve(),
+    stop: () => Promise.resolve(),
+    kill: () => Promise.resolve(),
+    remove: () => Promise.resolve(),
+    inspect: () => Promise.resolve({
+        Id: id,
+        Name: '/mock-container',
+        State: { Running: true },
+        NetworkSettings: { Networks: {} },
+    }),
+    logs: () => Promise.resolve(Buffer.from('')),
+    stats: () => Promise.resolve({}),
+    exec: () => Promise.resolve({ start: () => Promise.resolve({}) }),
+});
+/**
+ * Create a mock network for testing.
+ */
+const createMockNetwork = (id) => ({
+    id,
+    inspect: () => Promise.resolve({ Id: id, Name: 'mock-network' }),
+    remove: () => Promise.resolve(),
+    connect: () => Promise.resolve(),
+    disconnect: () => Promise.resolve(),
+});
+/**
+ * Test implementation of DockerClient.
+ *
+ * Returns mock responses for all operations.
+ * Useful for unit tests that don't need real Docker.
+ */
+export const DockerClientTest = Layer.succeed(DockerClient, {
+    _tag: 'DockerClient',
+    client: {},
+    ping: () => Effect.void,
+    version: () => Effect.succeed({
+        Version: '24.0.0',
+        ApiVersion: '1.43',
+        Os: 'linux',
+        Arch: 'amd64',
+    }),
+    listContainers: () => Effect.succeed([]),
+    getContainer: (id) => createMockContainer(id),
+    createContainer: (options) => Effect.succeed(createMockContainer(`mock-${options.name}`)),
+    listNetworks: () => Effect.succeed([]),
+    getNetwork: (id) => createMockNetwork(id),
+    createNetwork: (options) => Effect.succeed(createMockNetwork(`mock-${options.Name}`)),
+    getImage: (name) => ({
+        inspect: () => Promise.resolve({ Id: name }),
+        remove: () => Promise.resolve(),
+    }),
+    listImages: () => Effect.succeed([]),
+    pullImage: () => Effect.void,
+});
+/**
+ * Create a custom test client with specific mock behaviors.
+ */
+export const makeDockerClientTest = (overrides) => Layer.succeed(DockerClient, {
+    _tag: 'DockerClient',
+    client: {},
+    ping: () => Effect.void,
+    version: () => Effect.succeed({
+        Version: '24.0.0',
+        ApiVersion: '1.43',
+    }),
+    listContainers: () => Effect.succeed([]),
+    getContainer: (id) => createMockContainer(id),
+    createContainer: (options) => Effect.succeed(createMockContainer(`mock-${options.name}`)),
+    listNetworks: () => Effect.succeed([]),
+    getNetwork: (id) => createMockNetwork(id),
+    createNetwork: (options) => Effect.succeed(createMockNetwork(`mock-${options.Name}`)),
+    getImage: (name) => ({
+        inspect: () => Promise.resolve({ Id: name }),
+    }),
+    listImages: () => Effect.succeed([]),
+    pullImage: () => Effect.void,
+    ...overrides,
+});

package/dist/services/DockerErrors.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Docker-specific Error Types
+ *
+ * Typed errors for Docker operations that integrate with Effect's error handling.
+ */
+declare const DockerConnectionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DockerConnectionError";
+} & Readonly<A>;
+/**
+ * Base error for Docker connection issues.
+ * Thrown when the Docker daemon is unreachable or fails to respond.
+ */
+export declare class DockerConnectionError extends DockerConnectionError_base<{
+    readonly message: string;
+    readonly socketPath?: string;
+    readonly cause?: unknown;
+}> {
+    constructor(message: string, options?: {
+        socketPath?: string;
+        cause?: unknown;
+    });
+    toString(): string;
+}
+declare const DockerApiError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DockerApiError";
+} & Readonly<A>;
+/**
+ * Error for Docker API operation failures.
+ * Contains the operation name and status code when available.
+ */
+export declare class DockerApiError extends DockerApiError_base<{
+    readonly operation: string;
+    readonly message: string;
+    readonly statusCode?: number;
+    readonly cause?: unknown;
+}> {
+    constructor(operation: string, message: string, options?: {
+        statusCode?: number;
+        cause?: unknown;
+    });
+    toString(): string;
+}
+declare const DockerContainerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DockerContainerError";
+} & Readonly<A>;
+/**
+ * Error for container-specific operations.
+ */
+export declare class DockerContainerError extends DockerContainerError_base<{
+    readonly containerId: string;
+    readonly containerName?: string;
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    constructor(containerId: string, operation: string, message: string, options?: {
+        containerName?: string;
+        cause?: unknown;
+    });
+    toString(): string;
+}
+declare const DockerNetworkError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DockerNetworkError";
+} & Readonly<A>;
+/**
+ * Error for network-specific operations.
+ */
+export declare class DockerNetworkError extends DockerNetworkError_base<{
+    readonly networkId: string;
+    readonly networkName?: string;
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    constructor(networkId: string, operation: string, message: string, options?: {
+        networkName?: string;
+        cause?: unknown;
+    });
+    toString(): string;
+}
+declare const DockerImageError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DockerImageError";
+} & Readonly<A>;
+/**
+ * Error for image-specific operations.
+ */
+export declare class DockerImageError extends DockerImageError_base<{
+    readonly imageTag: string;
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    constructor(imageTag: string, operation: string, message: string, options?: {
+        cause?: unknown;
+    });
+    toString(): string;
+}
+declare const DockerVolumeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DockerVolumeError";
+} & Readonly<A>;
+/**
+ * Error for volume-specific operations.
+ */
+export declare class DockerVolumeError extends DockerVolumeError_base<{
+    readonly volumeName: string;
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    constructor(volumeName: string, operation: string, message: string, options?: {
+        cause?: unknown;
+    });
+    toString(): string;
+}
+/**
+ * Union type of all Docker errors for exhaustive handling.
+ */
+export type DockerError = DockerConnectionError | DockerApiError | DockerContainerError | DockerNetworkError | DockerImageError | DockerVolumeError;
+/**
+ * Type guard for DockerConnectionError.
+ */
+export declare const isDockerConnectionError: (error: unknown) => error is DockerConnectionError;
+/**
+ * Type guard for DockerApiError.
+ */
+export declare const isDockerApiError: (error: unknown) => error is DockerApiError;
+/**
+ * Type guard for any Docker error.
+ */
+export declare const isDockerError: (error: unknown) => error is DockerError;
+/**
+ * Helper to wrap unknown errors as DockerApiError.
+ */
+export declare const wrapAsDockerError: (operation: string, error: unknown) => DockerApiError;
+/**
+ * Determine if an error is transient and should be retried.
+ *
+ * Returns true for:
+ * - Connection errors (temporary network issues)
+ * - Specific HTTP status codes (429, 5xx)
+ * - Error messages matching transient patterns
+ */
+export declare const isTransientError: (error: unknown) => boolean;
+export {};
+//# sourceMappingURL=DockerErrors.d.ts.map

package/dist/services/DockerErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DockerErrors.d.ts","sourceRoot":"","sources":["../../src/services/DockerErrors.ts"],"names":[],"mappings":"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"}

package/dist/services/DockerErrors.js

@@ -0,0 +1,224 @@
+/**
+ * Docker-specific Error Types
+ *
+ * Typed errors for Docker operations that integrate with Effect's error handling.
+ */
+import { Data } from 'effect';
+/**
+ * Base error for Docker connection issues.
+ * Thrown when the Docker daemon is unreachable or fails to respond.
+ */
+export class DockerConnectionError extends Data.TaggedError('DockerConnectionError') {
+    constructor(message, options) {
+        super({
+            message,
+            ...(options?.socketPath !== undefined && { socketPath: options.socketPath }),
+            ...(options?.cause !== undefined && { cause: options.cause }),
+        });
+    }
+    toString() {
+        return `DockerConnectionError: ${this.message}${this.socketPath ? ` (socket: ${this.socketPath})` : ''}`;
+    }
+}
+/**
+ * Error for Docker API operation failures.
+ * Contains the operation name and status code when available.
+ */
+export class DockerApiError extends Data.TaggedError('DockerApiError') {
+    constructor(operation, message, options) {
+        super({
+            operation,
+            message,
+            ...(options?.statusCode !== undefined && { statusCode: options.statusCode }),
+            ...(options?.cause !== undefined && { cause: options.cause }),
+        });
+    }
+    toString() {
+        return `DockerApiError[${this.operation}]: ${this.message}${this.statusCode ? ` (status: ${this.statusCode})` : ''}`;
+    }
+}
+/**
+ * Error for container-specific operations.
+ */
+export class DockerContainerError extends Data.TaggedError('DockerContainerError') {
+    constructor(containerId, operation, message, options) {
+        super({
+            containerId,
+            operation,
+            message,
+            ...(options?.containerName !== undefined && { containerName: options.containerName }),
+            ...(options?.cause !== undefined && { cause: options.cause }),
+        });
+    }
+    toString() {
+        const name = this.containerName ?? this.containerId;
+        return `DockerContainerError[${name}/${this.operation}]: ${this.message}`;
+    }
+}
+/**
+ * Error for network-specific operations.
+ */
+export class DockerNetworkError extends Data.TaggedError('DockerNetworkError') {
+    constructor(networkId, operation, message, options) {
+        super({
+            networkId,
+            operation,
+            message,
+            ...(options?.networkName !== undefined && { networkName: options.networkName }),
+            ...(options?.cause !== undefined && { cause: options.cause }),
+        });
+    }
+    toString() {
+        const name = this.networkName ?? this.networkId;
+        return `DockerNetworkError[${name}/${this.operation}]: ${this.message}`;
+    }
+}
+/**
+ * Error for image-specific operations.
+ */
+export class DockerImageError extends Data.TaggedError('DockerImageError') {
+    constructor(imageTag, operation, message, options) {
+        super({
+            imageTag,
+            operation,
+            message,
+            cause: options?.cause,
+        });
+    }
+    toString() {
+        return `DockerImageError[${this.imageTag}/${this.operation}]: ${this.message}`;
+    }
+}
+/**
+ * Error for volume-specific operations.
+ */
+export class DockerVolumeError extends Data.TaggedError('DockerVolumeError') {
+    constructor(volumeName, operation, message, options) {
+        super({
+            volumeName,
+            operation,
+            message,
+            cause: options?.cause,
+        });
+    }
+    toString() {
+        return `DockerVolumeError[${this.volumeName}/${this.operation}]: ${this.message}`;
+    }
+}
+/**
+ * Type guard for DockerConnectionError.
+ */
+export const isDockerConnectionError = (error) => error instanceof DockerConnectionError ||
+    (typeof error === 'object' &&
+        error !== null &&
+        '_tag' in error &&
+        error._tag === 'DockerConnectionError');
+/**
+ * Type guard for DockerApiError.
+ */
+export const isDockerApiError = (error) => error instanceof DockerApiError ||
+    (typeof error === 'object' &&
+        error !== null &&
+        '_tag' in error &&
+        error._tag === 'DockerApiError');
+/**
+ * Type guard for any Docker error.
+ */
+export const isDockerError = (error) => {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    if (!('_tag' in error))
+        return false;
+    const tag = error._tag;
+    return [
+        'DockerConnectionError',
+        'DockerApiError',
+        'DockerContainerError',
+        'DockerNetworkError',
+        'DockerImageError',
+        'DockerVolumeError',
+    ].includes(tag);
+};
+/**
+ * Helper to wrap unknown errors as DockerApiError.
+ */
+export const wrapAsDockerError = (operation, error) => {
+    if (isDockerError(error)) {
+        return new DockerApiError(operation, String(error), { cause: error });
+    }
+    if (error instanceof Error) {
+        // Extract status code if present (dockerode pattern)
+        const statusCode = 'statusCode' in error ? error.statusCode : undefined;
+        return new DockerApiError(operation, error.message, {
+            ...(statusCode !== undefined && { statusCode }),
+            cause: error,
+        });
+    }
+    return new DockerApiError(operation, String(error), { cause: error });
+};
+/**
+ * Transient error status codes that should trigger retries.
+ *
+ * - 408: Request Timeout
+ * - 429: Too Many Requests
+ * - 500: Internal Server Error
+ * - 502: Bad Gateway
+ * - 503: Service Unavailable
+ * - 504: Gateway Timeout
+ */
+const TRANSIENT_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+/**
+ * Error messages that indicate transient failures.
+ */
+const TRANSIENT_ERROR_PATTERNS = [
+    /ECONNRESET/i,
+    /ECONNREFUSED/i,
+    /ETIMEDOUT/i,
+    /EPIPE/i,
+    /socket hang up/i,
+    /network is unreachable/i,
+    /connection refused/i,
+];
+/**
+ * Determine if an error is transient and should be retried.
+ *
+ * Returns true for:
+ * - Connection errors (temporary network issues)
+ * - Specific HTTP status codes (429, 5xx)
+ * - Error messages matching transient patterns
+ */
+export const isTransientError = (error) => {
+    // Connection errors are always transient
+    if (isDockerConnectionError(error)) {
+        return true;
+    }
+    // Check API errors for transient status codes
+    if (isDockerApiError(error)) {
+        if (error.statusCode && TRANSIENT_STATUS_CODES.has(error.statusCode)) {
+            return true;
+        }
+        // Check error message patterns
+        for (const pattern of TRANSIENT_ERROR_PATTERNS) {
+            if (pattern.test(error.message)) {
+                return true;
+            }
+        }
+    }
+    // Check raw errors
+    if (error instanceof Error) {
+        // Check for status code on raw error
+        if ('statusCode' in error) {
+            const statusCode = error.statusCode;
+            if (statusCode && TRANSIENT_STATUS_CODES.has(statusCode)) {
+                return true;
+            }
+        }
+        // Check message patterns
+        for (const pattern of TRANSIENT_ERROR_PATTERNS) {
+            if (pattern.test(error.message)) {
+                return true;
+            }
+        }
+    }
+    return false;
+};

package/dist/services/DockerRateLimiter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * DockerRateLimiter Service
+ *
+ * Provides semaphore-based rate limiting for Docker API operations.
+ * Prevents overwhelming the Docker daemon with too many concurrent requests.
+ */
+import { Context, Effect, Layer, Schedule, Duration } from 'effect';
+import { HarpoonConfig } from './HarpoonConfig';
+/**
+ * DockerRateLimiter service interface.
+ *
+ * Provides controlled access to Docker operations through semaphore-based
+ * rate limiting.
+ */
+export interface DockerRateLimiterService {
+    readonly _tag: 'DockerRateLimiter';
+    /**
+     * Execute an effect with a single permit.
+     * Waits for a permit if none are available.
+     */
+    readonly withPermit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Execute an effect with multiple permits.
+     * Useful for operations that are more resource-intensive.
+     */
+    readonly withPermits: (count: number) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Get the number of currently available permits.
+     */
+    readonly available: () => Effect.Effect<number>;
+}
+declare const DockerRateLimiter_base: Context.TagClass<DockerRateLimiter, "@harpoon/DockerRateLimiter", DockerRateLimiterService>;
+/**
+ * DockerRateLimiter service tag for dependency injection.
+ */
+export declare class DockerRateLimiter extends DockerRateLimiter_base {
+}
+/**
+ * Exponential backoff schedule for transient Docker API errors.
+ *
+ * - 5 retries maximum
+ * - Base delay: 100ms, exponentially increasing
+ * - Max delay: 30 seconds
+ * - Includes jitter to prevent thundering herd
+ */
+export declare const dockerRetrySchedule: Schedule.Schedule<[Duration.Duration, number], unknown, never>;
+/**
+ * Aggressive retry schedule for cleanup operations.
+ *
+ * - 3 retries maximum
+ * - Base delay: 200ms
+ * - Max delay: 10 seconds
+ * - Quick cleanup attempts with short delays
+ */
+export declare const cleanupRetrySchedule: Schedule.Schedule<[Duration.Duration, number], unknown, never>;
+/**
+ * Health check schedule with fixed intervals.
+ *
+ * - 1 second between checks
+ * - Used for container readiness polling
+ */
+export declare const healthCheckSchedule: Schedule.Schedule<number, unknown, never>;
+/**
+ * Live implementation of DockerRateLimiter.
+ *
+ * Uses HarpoonConfig.parallelLimit to determine semaphore size.
+ */
+export declare const DockerRateLimiterLive: Layer.Layer<DockerRateLimiter, never, HarpoonConfig>;
+/**
+ * Test implementation with unlimited permits.
+ *
+ * Useful for unit tests that don't need rate limiting.
+ */
+export declare const DockerRateLimiterTest: Layer.Layer<DockerRateLimiter, never, never>;
+/**
+ * Create a custom test rate limiter with specific permit count.
+ */
+export declare const makeDockerRateLimiterTest: (permits: number) => Layer.Layer<DockerRateLimiter, never, never>;
+export {};
+//# sourceMappingURL=DockerRateLimiter.d.ts.map

package/dist/services/DockerRateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DockerRateLimiter.d.ts","sourceRoot":"","sources":["../../src/services/DockerRateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEzF;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CACpB,KAAK,EAAE,MAAM,KACV,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEzE;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CACjD;;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,sBAGpC;CAAG;AAIN;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,gEAI/B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,gEAIhC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,2CAAuC,CAAC;AAwBxE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,sDAiBjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,8CAQhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,yBAAyB,mEAanC,CAAC"}