Network Architecture

HTTP Request Transport Engine

Execute reliable async HTTP communications with request deduplication, concurrency locking, signature generation, and global transport wrappers.

Why Use Huchi's HTTP Engine?

Standard network requests require manual abort controllers, header boilerplate, and duplicate request prevention. Huchi's HTTP subsystem manages these concerns natively:

Feature Native Fetch / Axios Huchi OS HTTP Engine (Call / call)
Request Locking Manual tracking flags required Automatic Inflight Deduplication: Identical requests block until finished.
URL Resolution Manual string concatenations Smart Endpoint Prefixing: Dynamically routes API paths or local scripts.
Signatures & Headers Manual per-request construction Auto-Signed Requests: Merges headers and crypto signatures seamlessly.
Error Normalization Requires manual try/catch blocks Normalized Responses: Always returns consistent state objects.

Core Transport Architecture

The network layer operates on three distinct abstraction tiers:

Production Implementation Code

1. Global Transport & Resolver Setup

Configures URL prefixing, API endpoint resolution, and exposes global window.get and window.post circuits:

import { call, Call } from "../HuchiOS/Request.js";

// --- GLOBAL ROUTING & API TRANSPORT CIRCUITS ---

// Resolves relative fragments into absolute environment URLs
const resolveFinalUrl = (url, forLocalPhp) => {
    if (!url || typeof url !== 'string') return null;
    if (url.startsWith('http://') || url.startsWith('https://')) return url;
    
    if (typeof window.prefixUrl === 'function') {
        return window.prefixUrl(url, forLocalPhp);
    }
    const base = window.backendEndPoint || '/';
    const prefix = forLocalPhp ? '' : 'api/';   
    return base + prefix + url.replace(/^\//, '');
};

// Global Async GET Circuit
window.get = async function(url, headers = null, forLocalPhp = false) {
    const finalUrl = resolveFinalUrl(url, forLocalPhp);
    if (!finalUrl) {
        console.error("HuchiOS Error: Invalid URL fragment provided to window.get()");
        return { success: false, error: "Invalid URL string argument" };
    }
    const configObject = { url: finalUrl, method: 'GET' };
    if (headers) configObject.header = headers;
    return await call(configObject);
};

// Global Async POST Circuit
window.post = async function(url, body = {}, headers = null, forLocalPhp = false) {
    const finalUrl = resolveFinalUrl(url, forLocalPhp);
    if (!finalUrl) {
        console.error("HuchiOS Error: Invalid URL fragment provided to window.post()");
        return { success: false, error: "Invalid URL string argument" };
    }
    const configObject = { url: finalUrl, method: 'POST', data: body };
    if (headers) configObject.header = headers;
    return await call(configObject);
};

2. Fluent Builder Pattern (Call Class)

Construct complex requests programmatically using chainable builder methods:

import { Call } from "../HuchiOS/Request.js";

// Fluent Request Construction
const response = await Call.init("accounting/v1/invoices")
    .method("POST")
    .header("X-Tenant-Key", "TNT-9821")
    .data({ status: "UNPAID", limit: 25 })
    .response();

if (response.ok) {
    const data = await response.json();
    console.log("Invoices loaded:", data);
}

3. Global Usage Inside Modules & Components

Use global transport circuits inside any UI component without extra imports:

// Inside a component or module controller
async function syncTenantManifest() {
    // 1. Send POST request to API endpoint (resolved to /api/tenant/sync)
    const result = await window.post('tenant/sync', { activeId: 'TNT-1002' });

    if (result.success) {
        console.log("Tenant synchronized successfully:", result.data);
    } else {
        console.error("Sync failed:", result.error);
    }

    // 2. Query direct local PHP script bypass (resolved to /local_health.php)
    const health = await window.get('local_health.php', null, true);
    console.log("Local system status:", health);
}

API Reference

Global Transport Helper Parameters

Parameter Type Default Description
url String Required URL path or endpoint fragment to call.
body / data Object {} Payload object sent as JSON body during POST requests.
headers Object null Custom headers appended to the request instance.
forLocalPhp Boolean false When true, bypasses the standard api/ path prefix.

Fluent Call Builder API Methods

Method Parameters Description
Call.init(url) url: String Instantiates a new fluent request builder.
.method(verb) verb: String Sets HTTP verb (GET, POST, PUT, DELETE).
.header(key, val) key: String, val: String Sets a specific request header.
.data(payload) payload: Object Attaches data payload to the request instance.
.response() none Executes the request and returns the standard Response promise.