jiren 1.0.1 → 1.0.3

package/README.md

@@ -5,11 +5,13 @@ Designed to be significantly faster than `fetch` and other Node/Bun HTTP clients
 
 ## Features
 
-- **Zero-Copy (Planned)**: Minimal overhead FFI.
-- **HTTP/1.1 & HTTP/3 (QUIC)**: Support for modern protocols.
+- **Blazing Fast**: Native implementation with minimal overhead.
+- **HTTP/3 (QUIC) Support**: First-class support for modern, high-performance connections.
+- **Automatic Redirects**: Recursively follows redirects (301, 302, etc.) with cycle protection.
+- **Type-Safe API**: Strict options (`GetRequestOptions`, `PostRequestOptions`) for better DX.
+- **Helper Methods**: Built-in `.json<T>()` parser and header accessors.
 - **Connection Pooling**: Reuse connections for maximum throughput.
 - **0-RTT Session Resumption**: Extremely fast subsequent requests.
-- **Prefetching**: Warm up connections in advance.
 
 ## Installation
 
@@ -19,14 +21,44 @@ bun add jiren
 
 ## Usage
 
-### Basic GET
+### Basic Requests
 
 ```typescript
-import { JirenClient } from "jiren"; // Class name is JirenClient
+import { JirenClient } from "jiren";
 
 const client = new JirenClient();
-const res = client.get("https://example.com");
-console.log(res.status, res.body.length);
+
+// Simple GET
+const res = client.get("https://google.com");
+console.log(res.status); // 200
+
+// JSON Parsing Helper
+const data = res.json<{ message: string }>();
+```
+
+### Advanced Options (Headers, Redirects, Body)
+
+Jiren enforces type safety. You cannot pass a body to a GET request!
+
+```typescript
+// GET with Headers
+client.get("https://api.example.com", {
+  headers: { Authorization: "Bearer token" },
+});
+
+// POST with JSON body
+client.post(
+  "https://api.example.com/users",
+  JSON.stringify({ name: "Jiren" }),
+  {
+    headers: { "Content-Type": "application/json" },
+  }
+);
+
+// Follow Redirects (e.g., http -> https)
+client.get("http://google.com", {
+  maxRedirects: 5, // Automatically follows up to 5 hops
+});
 ```
 
 ### Prefetching

package/components/client.ts

@@ -1,9 +1,13 @@
 import { CString, type Pointer } from "bun:ffi";
 import { lib } from "./native";
+import type {
+  RequestOptions,
+  GetRequestOptions,
+  PostRequestOptions,
+  HttpResponse,
+} from "../types";
 
 export class JirenClient {
-  // Using Pointer | number | null because Bun returns null or pointer-like object or number
-  // dlopen return types with FFIType.ptr are usually mapped to Pointer | null
   private ptr: Pointer | null;
 
   constructor() {
@@ -23,36 +27,100 @@ export class JirenClient {
   }
 
   /**
-   * Perform a GET request.
-   * @param url - The URL to request (http:// or https://)
-   * @returns Response object containing status and body string
+   * Perform a HTTP request.
+   * @param url - The URL to request
+   * @param options - Request options (method, headers, body)
+   * @returns Response object
    */
-  public get(url: string) {
+  public request(url: string, options: RequestOptions = {}): HttpResponse {
     if (!this.ptr) throw new Error("Client is closed");
 
-    // Buffer.from(string + "\0") is the safe way to create a CString buffer in Bun FFI
-    // We can also use `Buffer.from(url + "\0")
-    // Note: We keep the buffer alive for the duration of the call implicitly
+    const method = options.method || "GET";
+    const methodBuffer = Buffer.from(method + "\0");
     const urlBuffer = Buffer.from(url + "\0");
 
-    const respPtr = lib.symbols.zclient_get(this.ptr, urlBuffer);
-    return this.parseResponse(respPtr);
+    let headersBuffer: Buffer | null = null;
+    if (options.headers) {
+      const headerStr = Object.entries(options.headers)
+        .map(([k, v]) => `${k.toLowerCase()}: ${v}`)
+        .join("\r\n");
+      if (headerStr.length > 0) {
+        headersBuffer = Buffer.from(headerStr + "\0");
+      }
+    }
+
+    let bodyBuffer: Buffer | null = null;
+    if (options.body) {
+      const bodyStr =
+        typeof options.body === "string"
+          ? options.body
+          : JSON.stringify(options.body);
+      bodyBuffer = Buffer.from(bodyStr + "\0");
+    }
+
+    const respPtr = lib.symbols.zclient_request(
+      this.ptr,
+      methodBuffer,
+      urlBuffer,
+      headersBuffer,
+      bodyBuffer
+    );
+
+    const response = this.parseResponse(respPtr);
+
+    // Handle Redirects
+    if (
+      options.maxRedirects &&
+      options.maxRedirects > 0 &&
+      response.status >= 300 &&
+      response.status < 400 &&
+      response.headers &&
+      response.headers["location"]
+    ) {
+      const location = response.headers["location"];
+      const newUrl = new URL(location, url).toString(); // Resolve relative URLs
+      const newOptions = { ...options, maxRedirects: options.maxRedirects - 1 };
+
+      return this.request(newUrl, newOptions);
+    }
+
+    return response;
   }
 
-  /**
-   * Perform a POST request.
-   * @param url - The URL to request
-   * @param body - The body content string
-   * @returns Response object
-   */
-  public post(url: string, body: string) {
-    if (!this.ptr) throw new Error("Client is closed");
+  public get(url: string, options: GetRequestOptions = {}) {
+    return this.request(url, { ...options, method: "GET" });
+  }
 
-    const urlBuffer = Buffer.from(url + "\0");
-    const bodyBuffer = Buffer.from(body + "\0");
+  public post(
+    url: string,
+    body: string | object,
+    options: PostRequestOptions = {}
+  ) {
+    return this.request(url, { ...options, method: "POST", body });
+  }
+
+  public put(
+    url: string,
+    body: string | object,
+    options: PostRequestOptions = {}
+  ) {
+    return this.request(url, { ...options, method: "PUT", body });
+  }
+
+  public delete(url: string, options: GetRequestOptions = {}) {
+    return this.request(url, { ...options, method: "DELETE" });
+  }
 
-    const respPtr = lib.symbols.zclient_post(this.ptr, urlBuffer, bodyBuffer);
-    return this.parseResponse(respPtr);
+  public patch(
+    url: string,
+    body: string | object,
+    options: PostRequestOptions = {}
+  ) {
+    return this.request(url, { ...options, method: "PATCH", body });
+  }
+
+  public head(url: string, options: GetRequestOptions = {}) {
+    return this.request(url, { ...options, method: "HEAD" });
   }
 
   /**
@@ -73,19 +141,46 @@ export class JirenClient {
       throw new Error("Native request failed (returned null pointer)");
 
     try {
-      // In FFI, we can pass the pointer directly to these getters
       const status = lib.symbols.zclient_response_status(respPtr);
-      const len = Number(lib.symbols.zclient_response_body_len(respPtr));
+      const bodyLen = Number(lib.symbols.zclient_response_body_len(respPtr));
       const bodyPtr = lib.symbols.zclient_response_body(respPtr);
+      const headersLen = Number(
+        lib.symbols.zclient_response_headers_len(respPtr)
+      );
+      const headersPtr = lib.symbols.zclient_response_headers(respPtr);
 
       let bodyString = "";
-      if (len > 0 && bodyPtr) {
-        // CString wrapper works with Pointer objects
-        const cstr = new CString(bodyPtr);
-        bodyString = cstr.toString();
+      if (bodyLen > 0 && bodyPtr) {
+        // CString uses the full length if not null-terminated or we can just read the ptr
+        // Since we know the length, we can be more precise, but CString assumes null-terminated
+        // for now we trust it is null terminated from Zig
+        bodyString = new CString(bodyPtr).toString();
+      }
+
+      const headers: Record<string, string> = {};
+      if (headersLen > 0 && headersPtr) {
+        const headersStr = new CString(headersPtr).toString();
+        const lines = headersStr.split("\r\n");
+        for (const line of lines) {
+          if (!line) continue;
+          const colonIdx = line.indexOf(":");
+          if (colonIdx !== -1) {
+            const key = line.substring(0, colonIdx).trim().toLowerCase();
+            const val = line.substring(colonIdx + 1).trim();
+            headers[key] = val;
+          }
+        }
       }
 
-      return { status, body: bodyString };
+      return {
+        status,
+        body: bodyString,
+        headers,
+        json: <T = any>() => {
+          if (!bodyString) return null as T;
+          return JSON.parse(bodyString) as T;
+        },
+      };
     } finally {
       lib.symbols.zclient_response_free(respPtr);
     }

package/components/native.ts

@@ -37,10 +37,28 @@ export const ffiDef = {
     args: [FFIType.ptr],
     returns: FFIType.u64,
   },
+  zclient_response_headers: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  zclient_response_headers_len: {
+    args: [FFIType.ptr],
+    returns: FFIType.u64,
+  },
   zclient_response_free: {
     args: [FFIType.ptr],
     returns: FFIType.void,
   },
+  zclient_request: {
+    args: [
+      FFIType.ptr, // client
+      FFIType.cstring, // method
+      FFIType.cstring, // url
+      FFIType.cstring, // headers (nullable)
+      FFIType.cstring, // body (nullable)
+    ],
+    returns: FFIType.ptr,
+  },
 } as const;
 
 export const lib = dlopen(libPath, ffiDef);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiren",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "author": "",
   "main": "index.ts",
   "module": "index.ts",

package/types/index.ts

@@ -23,18 +23,27 @@ export interface BatchResult {
   requestsPerSecond: number;
 }
 
+/** Options for single HTTP requests */
 /** Options for single HTTP requests */
 export interface RequestOptions {
   /** HTTP method (default: GET) */
-  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD";
+  method?: string;
   /** Request headers */
   headers?: Record<string, string>;
   /** Request body (for POST, PUT, PATCH) */
   body?: string | object;
   /** Request timeout in milliseconds */
   timeout?: number;
+  /** Maximum number of redirects to follow (default: 0) */
+  maxRedirects?: number;
 }
 
+/** Options for requests without a body (GET, DELETE, HEAD) */
+export type GetRequestOptions = Omit<RequestOptions, "method" | "body">;
+
+/** Options for requests with a body (POST, PUT, PATCH) where body is a separate argument */
+export type PostRequestOptions = Omit<RequestOptions, "method" | "body">;
+
 /** HTTP Response */
 export interface HttpResponse {
   /** HTTP status code */
@@ -43,6 +52,8 @@ export interface HttpResponse {
   body: string;
   /** Response headers */
   headers?: Record<string, string>;
+  /** Helper to parse JSON body */
+  json: <T = any>() => T;
 }
 
 /** Configuration for JirenHttpClient */