@fastrack/starter-http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fastrack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @fastrack/starter-http
+
+HTTP client wrapper (fetch/undici, Node 18+): timeouts, retries for idempotent methods only, correlation ID propagation. No ad-hoc HTTP clients (design rule).
+
+Use a **singleton** client; pass the current request's correlation ID at **request time** so it is propagated on outbound calls:
+
+```ts
+// In a route handler (starter-web sets request.correlationId)
+const res = await app.httpClient.fetch("https://api.example.com/data", undefined, {
+  correlationId: request.correlationId,
+});
+```
+
+See [docs/starters.md](../../docs/starters.md).

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+export interface CreateHttpClientOptions {
+    timeoutMs?: number;
+    retries?: number;
+}
+/**
+ * Per-call options: pass the current request's correlation ID so it is propagated
+ * on the outbound request. Use singleton client and pass at request time.
+ */
+export interface HttpRequestOptions {
+    correlationId?: string;
+}
+/**
+ * Create an HTTP client with timeout and optional retries (idempotent only).
+ * Uses native fetch (Node 18+). Keep a singleton instance; pass correlationId
+ * at request time so it is propagated on each outbound call (e.g. from request.correlationId).
+ */
+export declare function createHttpClient(options?: CreateHttpClientOptions): {
+    fetch(url: string | URL, init?: RequestInit, requestOptions?: HttpRequestOptions): Promise<Response>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG;IACvE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtG,CAyCA"}

package/dist/client.js

@@ -0,0 +1,41 @@
+/**
+ * Create an HTTP client with timeout and optional retries (idempotent only).
+ * Uses native fetch (Node 18+). Keep a singleton instance; pass correlationId
+ * at request time so it is propagated on each outbound call (e.g. from request.correlationId).
+ */
+export function createHttpClient(options = {}) {
+    const { timeoutMs = 30_000, retries = 0 } = options;
+    async function doFetch(url, init, requestOptions, attempt = 0) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const headers = new Headers(init?.headers);
+        if (requestOptions?.correlationId) {
+            headers.set("x-correlation-id", requestOptions.correlationId);
+        }
+        try {
+            const res = await fetch(url, {
+                ...init,
+                signal: controller.signal,
+                headers,
+            });
+            clearTimeout(timeout);
+            const method = (init?.method ?? "GET").toUpperCase();
+            const isIdempotent = ["GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE"].includes(method);
+            if (!res.ok && isIdempotent && attempt < retries) {
+                return doFetch(url, init, requestOptions, attempt + 1);
+            }
+            return res;
+        }
+        catch (e) {
+            clearTimeout(timeout);
+            if (attempt < retries) {
+                return doFetch(url, init, requestOptions, attempt + 1);
+            }
+            throw e;
+        }
+    }
+    return {
+        fetch: (url, init, requestOptions) => doFetch(url, init, requestOptions),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IAGpE,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAEpD,KAAK,UAAU,OAAO,CACpB,GAAiB,EACjB,IAAkB,EAClB,cAAmC,EACnC,OAAO,GAAG,CAAC;QAEX,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3C,IAAI,cAAc,EAAE,aAAa,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,GAAG,IAAI;gBACP,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,OAAO;aACR,CAAC,CAAC;YACH,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACrD,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC3F,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,YAAY,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;gBACjD,OAAO,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;YACzD,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;YACzD,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,CAAC,GAAiB,EAAE,IAAkB,EAAE,cAAmC,EAAE,EAAE,CACpF,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,CAAC;KACrC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fastrack/starter-http — fetch/undici wrapper: timeouts, retries, correlation propagation.
+ */
+export { httpStarter } from "./plugin.js";
+export { createHttpClient } from "./client.js";
+export type { HttpStarterConfig, HttpClient } from "./plugin.js";
+export type { CreateHttpClientOptions, HttpRequestOptions } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fastrack/starter-http — fetch/undici wrapper: timeouts, retries, correlation propagation.
+ */
+export { httpStarter } from "./plugin.js";
+export { createHttpClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,14 @@
+import { type Static } from "@sinclair/typebox";
+import type { FastrackStarter } from "@fastrack/core";
+export declare const HttpStarterConfigSchema: import("@sinclair/typebox").TObject<{
+    timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    retries: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type HttpStarterConfig = Static<typeof HttpStarterConfigSchema>;
+export interface HttpClient {
+    fetch(url: string | URL, init?: RequestInit, requestOptions?: {
+        correlationId?: string;
+    }): Promise<Response>;
+}
+export declare const httpStarter: FastrackStarter<HttpStarterConfig>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,gBAAgB,CAAC;AAGvE,eAAO,MAAM,uBAAuB;;;EAGlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAEvE,MAAM,WAAW,UAAU;IACzB,KAAK,CACH,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,IAAI,CAAC,EAAE,WAAW,EAClB,cAAc,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtB;AAED,eAAO,MAAM,WAAW,EAAE,eAAe,CAAC,iBAAiB,CAQ1D,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,16 @@
+import { Type } from "@sinclair/typebox";
+import { createHttpClient } from "./client.js";
+export const HttpStarterConfigSchema = Type.Object({
+    timeoutMs: Type.Optional(Type.Number({ default: 30_000 })),
+    retries: Type.Optional(Type.Number({ default: 0 })),
+});
+export const httpStarter = {
+    name: "http",
+    configSchema: HttpStarterConfigSchema,
+    defaults: { timeoutMs: 30_000, retries: 0 },
+    register(app, _ctx, config) {
+        const client = createHttpClient({ timeoutMs: config.timeoutMs ?? 30_000, retries: config.retries ?? 0 });
+        app.decorate("httpClient", client);
+    },
+};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAGtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC,MAAM,CAAC;IACjD,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1D,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;CACpD,CAAC,CAAC;AAYH,MAAM,CAAC,MAAM,WAAW,GAAuC;IAC7D,IAAI,EAAE,MAAM;IACZ,YAAY,EAAE,uBAAuB;IACrC,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE;IAC3C,QAAQ,CAAC,GAAoB,EAAE,IAAqB,EAAE,MAAyB;QAC7E,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;QACzG,GAAG,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@fastrack/starter-http",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.34",
+    "fastify": "^5.1.0",
+    "@fastrack/core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "echo ok",
+    "test": "echo ok"
+  }
+}

package/src/client.ts

@@ -0,0 +1,62 @@
+export interface CreateHttpClientOptions {
+  timeoutMs?: number;
+  retries?: number;
+}
+
+/**
+ * Per-call options: pass the current request's correlation ID so it is propagated
+ * on the outbound request. Use singleton client and pass at request time.
+ */
+export interface HttpRequestOptions {
+  correlationId?: string;
+}
+
+/**
+ * Create an HTTP client with timeout and optional retries (idempotent only).
+ * Uses native fetch (Node 18+). Keep a singleton instance; pass correlationId
+ * at request time so it is propagated on each outbound call (e.g. from request.correlationId).
+ */
+export function createHttpClient(options: CreateHttpClientOptions = {}): {
+  fetch(url: string | URL, init?: RequestInit, requestOptions?: HttpRequestOptions): Promise<Response>;
+} {
+  const { timeoutMs = 30_000, retries = 0 } = options;
+
+  async function doFetch(
+    url: string | URL,
+    init?: RequestInit,
+    requestOptions?: HttpRequestOptions,
+    attempt = 0
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const headers = new Headers(init?.headers);
+    if (requestOptions?.correlationId) {
+      headers.set("x-correlation-id", requestOptions.correlationId);
+    }
+    try {
+      const res = await fetch(url, {
+        ...init,
+        signal: controller.signal,
+        headers,
+      });
+      clearTimeout(timeout);
+      const method = (init?.method ?? "GET").toUpperCase();
+      const isIdempotent = ["GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE"].includes(method);
+      if (!res.ok && isIdempotent && attempt < retries) {
+        return doFetch(url, init, requestOptions, attempt + 1);
+      }
+      return res;
+    } catch (e) {
+      clearTimeout(timeout);
+      if (attempt < retries) {
+        return doFetch(url, init, requestOptions, attempt + 1);
+      }
+      throw e;
+    }
+  }
+
+  return {
+    fetch: (url: string | URL, init?: RequestInit, requestOptions?: HttpRequestOptions) =>
+      doFetch(url, init, requestOptions),
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fastrack/starter-http — fetch/undici wrapper: timeouts, retries, correlation propagation.
+ */
+export { httpStarter } from "./plugin.js";
+export { createHttpClient } from "./client.js";
+export type { HttpStarterConfig, HttpClient } from "./plugin.js";
+export type { CreateHttpClientOptions, HttpRequestOptions } from "./client.js";

package/src/plugin.ts

@@ -0,0 +1,29 @@
+import { Type, type Static } from "@sinclair/typebox";
+import type { FastifyInstance } from "fastify";
+import type { FastrackStarter, FastrackContext } from "@fastrack/core";
+import { createHttpClient } from "./client.js";
+
+export const HttpStarterConfigSchema = Type.Object({
+  timeoutMs: Type.Optional(Type.Number({ default: 30_000 })),
+  retries: Type.Optional(Type.Number({ default: 0 })),
+});
+
+export type HttpStarterConfig = Static<typeof HttpStarterConfigSchema>;
+
+export interface HttpClient {
+  fetch(
+    url: string | URL,
+    init?: RequestInit,
+    requestOptions?: { correlationId?: string }
+  ): Promise<Response>;
+}
+
+export const httpStarter: FastrackStarter<HttpStarterConfig> = {
+  name: "http",
+  configSchema: HttpStarterConfigSchema,
+  defaults: { timeoutMs: 30_000, retries: 0 },
+  register(app: FastifyInstance, _ctx: FastrackContext, config: HttpStarterConfig) {
+    const client = createHttpClient({ timeoutMs: config.timeoutMs ?? 30_000, retries: config.retries ?? 0 });
+    app.decorate("httpClient", client);
+  },
+};

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}