Resolves #4

packages/smooth-api-py/README.md

@@ -17,6 +17,7 @@ pip install smoothapi-py
 - **Smart Retries:** Automatically detects HTTP status codes from `requests` and `httpx` exceptions. Retries on retryable codes (429, 500, 502, 503, 504) and re-raises client errors immediately.
 - **Graceful Fallbacks:** Optionally return cached or default data instantly when the circuit is `OPEN`, bypassing network IO entirely.
 - **Request Deduplication:** Automatically merges concurrent identical requests into a single network call (async only).
+- **Request Timeouts:** Configurable timeouts to automatically abort requests that hang indefinitely (async only).
 
 ## Usage
 
@@ -74,7 +75,9 @@ config = SmoothConfig(
     # Optional: return this exact object when the circuit is OPEN
     fallback={"status": "degraded", "data": []},
     # Optional: HTTP status codes to trigger a retry
-    retry_on=[429, 500, 502, 503, 504]
+    retry_on=[429, 500, 502, 503, 504],
+    # Optional: Abort a request attempt if it takes longer than 5000ms (Async Only)
+    timeout_ms=5000
 )
 
 @smooth_api(config)

packages/smooth-api-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "smoothapi-py"
-version = "1.2.3"
+version = "1.3.0"
 description = "API protection library — exponential backoff and circuit breaker"
 readme = "README.md"
 requires-python = ">=3.10"

packages/smooth-api-py/smooth_api/__init__.py

@@ -86,7 +86,10 @@ async def _execute():
 
                     for attempt in range(config.backoff.max_retries + 1):
                         try:
-                            result = await fn(*args, **kwargs)
+                            if config.timeout_ms:
+                                result = await asyncio.wait_for(fn(*args, **kwargs), timeout=config.timeout_ms / 1000.0)
+                            else:
+                                result = await fn(*args, **kwargs)
                             breaker.record_success(domain)
                             return result
                         except asyncio.CancelledError:
@@ -143,6 +146,9 @@ async def _execute():
                 import warnings
                 # Sync deduplication requires a thread-safe lock manager, which is currently unsupported
                 warnings.warn("Synchronous deduplication is not supported. Deduplication will be ignored for this function.", UserWarning, stacklevel=2)
+
+            if config.timeout_ms is not None:
+                raise NotImplementedError("timeout_ms is not supported for synchronous decorators. Please use your HTTP client's native timeout support.")
 
             @functools.wraps(fn)
             def wrapper(*args, **kwargs):  # type: ignore[misc]
@@ -197,6 +203,8 @@ def wrapper(*args, **kwargs):  # type: ignore[misc]
     return decorator
 
 
+__all__ = ['smooth_api', 'SmoothConfig', 'DeduplicationConfig', 'resilient_api', 'ResilientConfig']
+
 import warnings
 
 def resilient_api(*args, **kwargs):
@@ -208,6 +216,4 @@ def __init__(self, *args, **kwargs):
         warnings.warn("'ResilientConfig' is deprecated, use 'SmoothConfig' instead", DeprecationWarning, stacklevel=2)
         super().__init__(*args, **kwargs)
 
-__all__ = ['smooth_api', 'SmoothConfig', 'DeduplicationConfig', 'resilient_api', 'ResilientConfig']
-
 from .config import DeduplicationConfig  # re-export for convenience

packages/smooth-api-py/smooth_api/config.py

@@ -54,3 +54,5 @@ class SmoothConfig:
     on_non_retryable_error: Callable[[int, str], None] | None = None
     # When set, enables request deduplication for async-decorated functions.
     deduplication: Optional[DeduplicationConfig] = None
+    # Maximum duration in milliseconds before a request attempt is aborted.
+    timeout_ms: Optional[int] = None

packages/smooth-api-py/tests/test_timeout.py

@@ -0,0 +1,33 @@
+import asyncio
+import pytest
+from smooth_api import smooth_api, SmoothConfig
+from smooth_api.config import BackoffConfig
+
+@pytest.mark.asyncio
+async def test_async_timeout_aborts_and_retries():
+    call_count = 0
+
+    @smooth_api(SmoothConfig(
+        timeout_ms=100,
+        backoff=BackoffConfig(max_retries=1, base_delay=0.01)
+    ))
+    async def fetch_data():
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            await asyncio.sleep(0.5)  # Should timeout
+            return "delayed"
+        return "success"
+
+    result = await fetch_data()
+    assert result == "success"
+    assert call_count == 2
+
+def test_sync_timeout_raises_not_implemented():
+    with pytest.raises(NotImplementedError, match="timeout_ms is not supported for synchronous decorators"):
+        @smooth_api(SmoothConfig(
+            timeout_ms=100,
+            backoff=BackoffConfig(max_retries=1, base_delay=0.01)
+        ))
+        def fetch_data_sync():
+            return "success"

packages/smooth-api-ts/README.md

@@ -17,6 +17,7 @@ npm install @codingaryan/smoothapi
 - **Smart Retries:** Automatically retries on specific HTTP status codes (e.g., 429, 500, 502, 503, 504) while throwing immediately on client errors (400, 401, 404).
 - **Graceful Fallbacks:** Optionally serve cached or default data instantly when the circuit is `OPEN`.
 - **Request Deduplication:** Automatically couples concurrent identical requests into a single network call.
+- **Request Timeouts:** Configurable timeouts to automatically abort requests that hang indefinitely.
 
 ## Usage
 
@@ -69,7 +70,9 @@ const fetchWithRetry = createSmoothFetch({
   // Optional: Return this instead of throwing when the circuit is OPEN
   fallback: { error: "Service degraded, returning stale data." },
   // Optional: Custom status codes to retry on
-  retryOn: [429, 500, 502, 503, 504]
+  retryOn: [429, 500, 502, 503, 504],
+  // Optional: Abort a request attempt if it takes longer than 5000ms
+  timeoutMs: 5000
 });
 
 async function main() {

packages/smooth-api-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingaryan/smoothapi",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "API protection library — exponential backoff and circuit breaker for fetch",
   "type": "module",
   "main": "./dist/index.js",

packages/smooth-api-ts/src/dedup.ts

@@ -61,8 +61,8 @@ export class RequestDeduplicator {
    * otherwise attach to the existing Promise.  In either case the caller
    * receives `Response.clone()` so body streams are independent.
    *
-   * @param url     - Same value passed to the outer resilientFetch.
-   * @param options - Same value passed to the outer resilientFetch.
+   * @param url     - Same value passed to the outer smoothFetch.
+   * @param options - Same value passed to the outer smoothFetch.
    * @param fetcher - A thunk that performs the actual network call.
    */
   execute<R>(

packages/smooth-api-ts/src/index.ts

@@ -1,6 +1,6 @@
 import { CircuitBreakerState } from "./state.js";
 import { calculateBackoff, sleep } from "./utils/backoff.js";
-import { CircuitOpenError, ResilientFetchConfig } from "./types.js";
+import { CircuitOpenError, SmoothFetchConfig } from "./types.js";
 import { RequestDeduplicator } from "./dedup.js";
 
 const BACKOFF_DEFAULTS = {
@@ -11,7 +11,7 @@ const BACKOFF_DEFAULTS = {
 
 const DEFAULT_RETRY_ON = [429, 500, 502, 503, 504];
 
-export function createSmoothFetch<T>(globalConfig: ResilientFetchConfig<T>) {
+export function createSmoothFetch<T>(globalConfig: SmoothFetchConfig<T>) {
   const backoffConfig = { ...BACKOFF_DEFAULTS, ...globalConfig.backoff };
   const retryOn = globalConfig.retryOn ?? DEFAULT_RETRY_ON;
   const breaker = new CircuitBreakerState(globalConfig.circuitBreaker);
@@ -41,8 +41,25 @@ export function createSmoothFetch<T>(globalConfig: ResilientFetchConfig<T>) {
 
       const run = async (): Promise<Response | T> => {
         for (let attempt = 0; attempt <= backoffConfig.maxRetries; attempt++) {
+          let timeoutId: ReturnType<typeof setTimeout> | undefined;
+          let currentOptions = options;
+          let controller: AbortController | undefined;
+
+          if (globalConfig.timeoutMs) {
+            controller = new AbortController();
+            if (options?.signal) {
+              const userSignal = options.signal;
+              userSignal.addEventListener('abort', () => controller?.abort(userSignal.reason));
+              if (userSignal.aborted) {
+                controller.abort(userSignal.reason);
+              }
+            }
+            currentOptions = { ...options, signal: controller.signal };
+            timeoutId = setTimeout(() => controller?.abort(new Error('Request Timeout')), globalConfig.timeoutMs);
+          }
+
           try {
-            const response = await fetch(url, options);
+            const response = await fetch(url, currentOptions);
 
             // fetch() resolves for any HTTP status. Retryable codes need to be
             // treated as failures manually.
@@ -89,10 +106,17 @@ export function createSmoothFetch<T>(globalConfig: ResilientFetchConfig<T>) {
             lastError = err;
             breaker.recordFailure(domain);
 
+            // Do not retry if the user explicitly aborted the request
+            if (options?.signal?.aborted) {
+              throw err;
+            }
+
             // Don't sleep after the final attempt
             if (attempt < backoffConfig.maxRetries) {
               await sleep(calculateBackoff(attempt, backoffConfig));
             }
+          } finally {
+            if (timeoutId) clearTimeout(timeoutId);
           }
         }
 

packages/smooth-api-ts/src/types.ts

@@ -13,7 +13,7 @@ export type DeduplicationKeyFn = (
 export interface DeduplicationConfig {
   /**
    * Custom function to compute the deduplication key.
-   * Receives the same (url, options) passed to resilientFetch.
+   * Receives the same (url, options) passed to smoothFetch.
    * Defaults to the stringified URL (method-agnostic).
    */
   keyFn?: DeduplicationKeyFn;
@@ -38,7 +38,7 @@ export interface CircuitBreakerConfig {
 }
 
 // T types the fallback payload so callers get inference at the use site.
-export interface ResilientFetchConfig<T = unknown> {
+export interface SmoothFetchConfig<T = unknown> {
   backoff?: Partial<BackoffConfig>;
   circuitBreaker?: Partial<CircuitBreakerConfig>;
   fallback?: T;    // returned immediately on an OPEN circuit, no network IO
@@ -50,6 +50,11 @@ export interface ResilientFetchConfig<T = unknown> {
    * Pass an empty object `{}` to activate with the default key function.
    */
   deduplication?: DeduplicationConfig;
+  /**
+   * Maximum duration in milliseconds before a request attempt is aborted.
+   * Applied per-attempt. If aborted, the request is considered a failure and may be retried.
+   */
+  timeoutMs?: number;
 }
 
 // Thrown when the circuit is OPEN and no fallback is configured.

packages/smooth-api-ts/tests/deduplication.test.ts

@@ -33,14 +33,14 @@ describe('Request Deduplication', () => {
     globalThis.fetch = makeStubFetch(() => new Response('{}', { status: 200 }), counter);
 
     try {
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
       });
 
       await Promise.all([
-        resilientFetch('http://example.com/users/1'),
-        resilientFetch('http://example.com/users/1'),
-        resilientFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/1'),
       ]);
 
       assert.equal(counter.calls, 3, 'Without deduplication, each call hits the network');
@@ -64,15 +64,15 @@ describe('Request Deduplication', () => {
     };
 
     try {
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
         deduplication: {},
       });
 
       const results = await Promise.all([
-        resilientFetch('http://example.com/users/1'),
-        resilientFetch('http://example.com/users/1'),
-        resilientFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/1'),
       ]);
 
       assert.equal(counter.calls, 1, 'Exactly one network call should be made for 3 concurrent identical requests');
@@ -96,14 +96,14 @@ describe('Request Deduplication', () => {
     };
 
     try {
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
         deduplication: {},
       });
 
       await Promise.all([
-        resilientFetch('http://example.com/users/1'),
-        resilientFetch('http://example.com/users/2'),
+        smoothFetch('http://example.com/users/1'),
+        smoothFetch('http://example.com/users/2'),
       ]);
 
       assert.equal(counter.calls, 2, 'Different URLs must each trigger their own network call');
@@ -122,15 +122,15 @@ describe('Request Deduplication', () => {
     };
 
     try {
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
         deduplication: {},
       });
 
       // First call — completes before the second.
-      await resilientFetch('http://example.com/data');
+      await smoothFetch('http://example.com/data');
       // Second call — should trigger a new network request.
-      await resilientFetch('http://example.com/data');
+      await smoothFetch('http://example.com/data');
 
       assert.equal(counter.calls, 2, 'Sequential requests should each hit the network');
     } finally {
@@ -146,15 +146,15 @@ describe('Request Deduplication', () => {
     };
 
     try {
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
         deduplication: {},
       });
 
       const results = await Promise.allSettled([
-        resilientFetch('http://example.com/flaky'),
-        resilientFetch('http://example.com/flaky'),
-        resilientFetch('http://example.com/flaky'),
+        smoothFetch('http://example.com/flaky'),
+        smoothFetch('http://example.com/flaky'),
+        smoothFetch('http://example.com/flaky'),
       ]);
 
       for (const result of results) {
@@ -179,7 +179,7 @@ describe('Request Deduplication', () => {
     try {
       // Custom key returns only the HTTP method — two GETs share the same key
       // and are therefore deduplicated regardless of their URLs.
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
         deduplication: {
           keyFn: (_url, options) => (options?.method ?? 'GET').toUpperCase(),
@@ -188,8 +188,8 @@ describe('Request Deduplication', () => {
 
       // Two concurrent GETs to different URLs — same key → deduplicated.
       await Promise.all([
-        resilientFetch('http://example.com/a', { method: 'GET' }),
-        resilientFetch('http://example.com/b', { method: 'GET' }),
+        smoothFetch('http://example.com/a', { method: 'GET' }),
+        smoothFetch('http://example.com/b', { method: 'GET' }),
       ]);
 
       assert.equal(counter.calls, 1, 'Both GETs share a key via custom keyFn → single fetch');
@@ -209,7 +209,7 @@ describe('Request Deduplication', () => {
     };
 
     try {
-      const resilientFetch = createSmoothFetch({
+      const smoothFetch = createSmoothFetch({
         backoff: { maxRetries: 0, baseDelay: 0, maxDelay: 0 },
         deduplication: {
           keyFn: (_url, options) =>
@@ -219,8 +219,8 @@ describe('Request Deduplication', () => {
 
       // Two concurrent POSTs — keyFn returns null, so they bypass deduplication.
       await Promise.all([
-        resilientFetch('http://example.com/users', { method: 'POST' }),
-        resilientFetch('http://example.com/users', { method: 'POST' }),
+        smoothFetch('http://example.com/users', { method: 'POST' }),
+        smoothFetch('http://example.com/users', { method: 'POST' }),
       ]);
 
       assert.equal(counter.calls, 2, 'null key disables deduplication for this pair of POSTs');