@telorun/http-client 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,84 @@
+# Telo HTTP Client Standard Specification (v1.0 Draft)
+
+## Overview
+
+The `Http.Request` (and optionally `Http.Client`) definitions represent outgoing HTTP calls made by the Telo kernel to external services.
+Because different programming languages implement HTTP clients differently (e.g., `fetch` in Node.js, `reqwest` in Rust), all Telo HTTP Client modules MUST adhere to this exact behavior to ensure cross-language compatibility.
+
+---
+
+## 1. The Request Contract (Input Serialization)
+
+When the Telo kernel executes an `Http.Request`, the underlying module must construct the outgoing request according to strict rules.
+
+- **Headers Normalization:** All header keys provided in the manifest MUST be normalized to lowercase before sending.
+- **Query Parameters:** If `query` is provided as an object, the module MUST safely URL-encode the keys and values and append them to the `url`.
+- **Payload Serialization (Body):**
+- If the `headers` include `content-type: application/json` (which should be the default if `body` is an object), the module MUST serialize the `body` to a JSON string.
+- If the `content-type` is `application/x-www-form-urlencoded`, the module MUST serialize the object into a URL-encoded string.
+
+---
+
+## 2. The Response Contract (Output Deserialization)
+
+The output of an `Http.Request` becomes available to the Telo engine (e.g., for mapping via CEL expressions). The underlying engine MUST return a standardized **Telo Response Object**.
+
+### Standardized Return Object
+
+```json
+{
+  "status": 200,
+  "headers": {
+    "content-type": "application/json",
+    "x-ratelimit-remaining": "99"
+  },
+  "body": {
+    "userId": 1,
+    "title": "Hello World"
+  }
+}
+```
+
+- **Header Normalization:** The module MUST normalize all incoming response headers to lowercase keys.
+- **Body Deserialization Rules:**
+- **JSON:** If the response header `content-type` includes `application/json`, the module MUST attempt to parse the response body as a JSON object. _Edge Case:_ If the response is empty (0 bytes) but claims to be JSON, the module MUST return `null` for the body, not throw a parsing error.
+- **Text/Other:** For any other content type, or if JSON parsing fails gracefully, the `body` MUST be returned as a raw String.
+
+---
+
+## 3. Error Handling Contract (Network vs. HTTP)
+
+It is crucial to differentiate between an HTTP error (the external server responded) and a Network error (the kernel couldn't reach the server).
+
+### 3.1. HTTP Status Errors (4xx and 5xx)
+
+- **Standard:** By default, HTTP status codes like `400`, `404`, or `500` **MUST NOT** throw a kernel execution error.
+- They are considered successful _network_ executions. The module MUST return the standard Telo Response Object with the respective `status` code. It is up to the Telo manifest author to handle these via CEL mappings (e.g., `${{ result.status == 200 ? result.body : throw('API Failed') }}`).
+
+### 3.2. Network & Engine Errors
+
+If the request fails at the network layer (e.g., DNS resolution failure, connection refused, SSL error), the module MUST throw a standardized **Telo Network Error** that stops execution.
+
+**Standardized Error Format:**
+
+```json
+{
+  "error": "NetworkError",
+  "code": "CONNECTION_REFUSED",
+  "message": "Failed to connect to api.external.com",
+  "details": {
+    "url": "https://api.external.com/data"
+  }
+}
+```
+
+_Valid `code` enumerations MUST include:_ `TIMEOUT`, `CONNECTION_REFUSED`, `DNS_RESOLUTION_FAILED`, `SSL_ERROR`. Modules must map their native engine errors to these generic codes.
+
+---
+
+## 4. Execution Policies (Timeouts & Redirects)
+
+To prevent hanging processes, Telo enforces strict default limits on outgoing requests.
+
+- **Timeouts:** The module MUST enforce a default request timeout of **10,000 milliseconds (10 seconds)** unless overridden in the manifest. If the timeout is reached, it MUST throw a `NetworkError` with the code `TIMEOUT`.
+- **Redirects:** The module MUST automatically follow `301` and `302` redirects, up to a maximum of **5 redirects**, to prevent infinite redirect loops.

package/dist/http-request-controller.d.ts

@@ -1,5 +1,5 @@
-import { Readable } from "stream";
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { Readable } from "stream";
 interface TeloResponse {
     status: number;
     headers: Record<string, string>;

package/dist/http-request-controller.js

@@ -151,9 +151,18 @@ class HttpRequestResource {
             if (!client) {
                 throw new Error(`Http.Client "${clientName}" not found`);
             }
-            clientBaseUrl = client.baseUrl ?? "";
-            clientHeaders = normalizeHeaders(client.headers ?? {});
-            clientTimeout = client.timeout ?? DEFAULT_TIMEOUT;
+            const clientConfig = typeof client.snapshot === "function"
+                ? client.snapshot()
+                : client;
+            const resolvedBaseUrl = ctx.expandValue(clientConfig.baseUrl ?? "", input ?? {});
+            clientBaseUrl = typeof resolvedBaseUrl === "string" ? resolvedBaseUrl : "";
+            const resolvedHeaders = ctx.expandValue(clientConfig.headers ?? {}, input ?? {});
+            clientHeaders = normalizeHeaders((resolvedHeaders ?? {}));
+            const resolvedTimeout = ctx.expandValue(clientConfig.timeout ?? DEFAULT_TIMEOUT, input ?? {});
+            clientTimeout =
+                typeof resolvedTimeout === "number" && Number.isFinite(resolvedTimeout)
+                    ? resolvedTimeout
+                    : DEFAULT_TIMEOUT;
         }
         // Expand template fields from manifest.inputs using runtime input as context
         // Manifest-level fields (url, method, etc.) serve as defaults when inputs is absent

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@telorun/http-client",
-  "version": "0.1.2",
+  "version": "0.1.4",
+  "description": "Telo HTTP Client module - HTTP client resource kinds for Telo manifests.",
+  "keywords": [
+    "telo",
+    "http",
+    "client",
+    "request"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "modules/http-client/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
   "type": "module",
   "exports": {
     "./http-client": {
@@ -13,10 +31,11 @@
     }
   },
   "files": [
-    "dist/**"
+    "dist",
+    "src/**"
   ],
   "dependencies": {
-    "@telorun/sdk": "0.2.6"
+    "@telorun/sdk": "0.2.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/http-client-controller.ts

@@ -0,0 +1,34 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+
+interface HttpClientManifest {
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+  followRedirects?: boolean;
+}
+
+class HttpClientResource implements ResourceInstance {
+  readonly metadata: { name: string; module: string; [key: string]: any };
+
+  constructor(private readonly manifest: any) {
+    this.metadata = manifest.metadata ?? {};
+  }
+
+  snapshot() {
+    return {
+      baseUrl: this.manifest.baseUrl ?? "",
+      headers: this.manifest.headers ?? {},
+      timeout: this.manifest.timeout ?? 10000,
+      followRedirects: this.manifest.followRedirects ?? true,
+    };
+  }
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: HttpClientManifest,
+  _ctx: ResourceContext,
+): Promise<HttpClientResource> {
+  return new HttpClientResource(resource);
+}

package/src/http-request-controller.ts

@@ -0,0 +1,314 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { PassThrough, Readable } from "stream";
+
+const MAX_REDIRECTS = 5;
+const DEFAULT_TIMEOUT = 10000;
+
+interface TeloResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+interface NetworkErrorPayload {
+  error: "NetworkError";
+  code: "TIMEOUT" | "CONNECTION_REFUSED" | "DNS_RESOLUTION_FAILED" | "SSL_ERROR";
+  message: string;
+  details: { url: string };
+}
+
+function createNetworkError(
+  code: NetworkErrorPayload["code"],
+  message: string,
+  url: string,
+): Error {
+  const payload: NetworkErrorPayload = {
+    error: "NetworkError",
+    code,
+    message,
+    details: { url },
+  };
+  const err = new Error(message);
+  (err as any).networkError = payload;
+  (err as any).code = code;
+  Object.assign(err, payload);
+  return err;
+}
+
+function mapNetworkError(err: unknown, url: string): never {
+  const e = err as Error;
+  if (e.name === "AbortError") {
+    throw createNetworkError("TIMEOUT", `Request timed out`, url);
+  }
+  const msg = e.message?.toLowerCase() ?? "";
+  if (msg.includes("econnrefused") || msg.includes("connection refused")) {
+    throw createNetworkError("CONNECTION_REFUSED", e.message, url);
+  }
+  if (msg.includes("enotfound") || msg.includes("getaddrinfo") || msg.includes("dns")) {
+    throw createNetworkError("DNS_RESOLUTION_FAILED", e.message, url);
+  }
+  if (msg.includes("ssl") || msg.includes("cert") || msg.includes("tls")) {
+    throw createNetworkError("SSL_ERROR", e.message, url);
+  }
+  throw createNetworkError("CONNECTION_REFUSED", e.message, url);
+}
+
+function normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    result[key.toLowerCase()] = value;
+  }
+  return result;
+}
+
+async function executeRequest(
+  url: string,
+  method: string,
+  headers: Record<string, string>,
+  body: string | undefined,
+  timeout: number,
+  stream = false,
+): Promise<TeloResponse> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  let currentUrl = url;
+  let redirectsLeft = MAX_REDIRECTS;
+
+  try {
+    while (true) {
+      const response = await fetch(currentUrl, {
+        method,
+        headers,
+        body,
+        redirect: "manual",
+        signal: controller.signal,
+      });
+
+      // Handle redirects manually (limit to MAX_REDIRECTS)
+      if ((response.status === 301 || response.status === 302) && redirectsLeft > 0) {
+        const location = response.headers.get("location");
+        if (location) {
+          currentUrl = location.startsWith("http")
+            ? location
+            : new URL(location, currentUrl).toString();
+          redirectsLeft--;
+          // For redirects, switch to GET and drop body per HTTP spec
+          method = "GET";
+          body = undefined;
+          delete headers["content-length"];
+          continue;
+        }
+      }
+
+      // Normalize response headers
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key.toLowerCase()] = value;
+      });
+
+      // Stream mode: pump body into a PassThrough eagerly so data flows immediately
+      if (stream) {
+        const webStream = response.body;
+        const body = new PassThrough();
+        (async () => {
+          if (!webStream) {
+            body.end();
+            return;
+          }
+          const reader = webStream.getReader();
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              body.push(Buffer.from(value));
+            }
+            body.end();
+          } catch (err) {
+            body.destroy(err as Error);
+          } finally {
+            reader.releaseLock();
+          }
+        })();
+        return { status: response.status, headers: responseHeaders, body };
+      }
+
+      // Deserialize body
+      const contentType = responseHeaders["content-type"] ?? "";
+      let responseBody: unknown;
+
+      if (contentType.includes("application/json")) {
+        const text = await response.text();
+        responseBody = text.length === 0 ? null : JSON.parse(text);
+      } else {
+        responseBody = await response.text();
+      }
+
+      return { status: response.status, headers: responseHeaders, body: responseBody };
+    }
+  } catch (err) {
+    mapNetworkError(err, url);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function executeWithRetry(
+  url: string,
+  method: string,
+  headers: Record<string, string>,
+  body: string | undefined,
+  timeout: number,
+  retriesLeft: number,
+  stream = false,
+): Promise<TeloResponse> {
+  try {
+    return await executeRequest(url, method, headers, body, timeout, stream);
+  } catch (err) {
+    if (retriesLeft > 0 && (err as any).error === "NetworkError") {
+      return executeWithRetry(url, method, headers, body, timeout, retriesLeft - 1, stream);
+    }
+    throw err;
+  }
+}
+
+interface HttpRequestInputs {
+  url: string;
+  method?: string;
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  body?: string | Record<string, unknown>;
+}
+
+interface HttpRequestManifest extends HttpRequestInputs {
+  client?: string;
+  timeout?: number;
+  throwOnHttpError?: boolean;
+  retries?: number;
+  mode?: "buffer" | "stream";
+  inputs?: HttpRequestInputs;
+}
+
+class HttpRequestResource implements ResourceInstance {
+  constructor(
+    private readonly manifest: HttpRequestManifest,
+    private readonly ctx: ResourceContext,
+  ) {}
+
+  async invoke(input: any): Promise<TeloResponse | Readable> {
+    const ctx = this.ctx;
+    const m = this.manifest;
+
+    // Resolve client config
+    let clientBaseUrl = "";
+    let clientHeaders: Record<string, string> = {};
+    let clientTimeout = DEFAULT_TIMEOUT;
+
+    if (m.client) {
+      const clientName = ctx.expandValue(m.client, input ?? {}) as string;
+      const client: any = ctx.getResourcesByName("Client", clientName);
+      if (!client) {
+        throw new Error(`Http.Client "${clientName}" not found`);
+      }
+
+      const clientConfig =
+        typeof client.snapshot === "function"
+          ? (client.snapshot() as Record<string, unknown>)
+          : client;
+
+      const resolvedBaseUrl = ctx.expandValue(clientConfig.baseUrl ?? "", input ?? {});
+      clientBaseUrl = typeof resolvedBaseUrl === "string" ? resolvedBaseUrl : "";
+
+      const resolvedHeaders = ctx.expandValue(clientConfig.headers ?? {}, input ?? {});
+      clientHeaders = normalizeHeaders((resolvedHeaders ?? {}) as Record<string, string>);
+
+      const resolvedTimeout = ctx.expandValue(clientConfig.timeout ?? DEFAULT_TIMEOUT, input ?? {});
+      clientTimeout =
+        typeof resolvedTimeout === "number" && Number.isFinite(resolvedTimeout)
+          ? resolvedTimeout
+          : DEFAULT_TIMEOUT;
+    }
+
+    // Expand template fields from manifest.inputs using runtime input as context
+    // Manifest-level fields (url, method, etc.) serve as defaults when inputs is absent
+    const manifestInputs: HttpRequestInputs = {
+      url: m.url,
+      method: m.method,
+      query: m.query,
+      headers: m.headers,
+      body: m.body,
+      ...m.inputs,
+    };
+    const resolved = ctx.expandValue(manifestInputs, input ?? {}) as HttpRequestInputs;
+    const rawUrl = resolved.url as string;
+    const method = ((resolved.method ?? "GET") || "GET").toUpperCase();
+    const requestHeaders = normalizeHeaders((resolved.headers ?? {}) as Record<string, string>);
+    const query = (resolved.query ?? {}) as Record<string, string>;
+    const body = resolved.body;
+    const effectiveTimeout = m.timeout ?? clientTimeout;
+    const retries = m.retries ?? 0;
+    const throwOnHttpError = m.throwOnHttpError ?? false;
+
+    // Build URL
+    let fullUrl = rawUrl.startsWith("http") ? rawUrl : `${clientBaseUrl}${rawUrl}`;
+
+    // Append query params
+    const queryEntries = Object.entries(query);
+    if (queryEntries.length > 0) {
+      const params = new URLSearchParams(queryEntries);
+      fullUrl = `${fullUrl}${fullUrl.includes("?") ? "&" : "?"}${params.toString()}`;
+    }
+
+    // Merge headers: client defaults < request-specific
+    const mergedHeaders: Record<string, string> = { ...clientHeaders, ...requestHeaders };
+
+    // Serialize body
+    let serializedBody: string | undefined;
+    if (body !== undefined) {
+      if (typeof body === "object" && body !== null) {
+        const contentType = mergedHeaders["content-type"] ?? "application/json";
+        if (!mergedHeaders["content-type"]) {
+          mergedHeaders["content-type"] = "application/json";
+        }
+        if (contentType.includes("application/x-www-form-urlencoded")) {
+          serializedBody = new URLSearchParams(body as Record<string, string>).toString();
+        } else {
+          // Default to JSON
+          mergedHeaders["content-type"] = mergedHeaders["content-type"] ?? "application/json";
+          serializedBody = JSON.stringify(body);
+        }
+      } else {
+        serializedBody = String(body);
+      }
+    }
+
+    const response = await executeWithRetry(
+      fullUrl,
+      method,
+      mergedHeaders,
+      serializedBody,
+      effectiveTimeout,
+      retries,
+      m.mode === "stream",
+    );
+
+    if (throwOnHttpError && response.status >= 400) {
+      throw new Error(`HTTP ${response.status} error from ${fullUrl}`);
+    }
+
+    if (m.mode === "stream") {
+      return response.body as Readable;
+    }
+
+    return response;
+  }
+}
+
+export function register(): void {}
+
+export async function create(
+  resource: HttpRequestManifest,
+  ctx: ResourceContext,
+): Promise<HttpRequestResource> {
+  return new HttpRequestResource(resource, ctx);
+}