Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Host Communication

The Host API namespace provides low-level HTTP communication with the Desktop Homunculus server. This module handles the foundational HTTP client functionality used internally by all other SDK modules.

Overview

[!Note] This module is primarily for internal SDK use.

Most MOD developers should use the higher-level namespaces like gpt, vrm, commands, etc., rather than calling host functions directly.

The host module provides:

  • Base URL configuration for the Desktop Homunculus server
  • URL construction utilities with query parameter support
  • HTTP methods (GET, POST, PUT) with automatic error handling
  • Type-safe response handling

Base Configuration

The host module connects to the Desktop Homunculus server running on:

  • Base URL: http://localhost:3100
  • Protocol: HTTP with JSON content type
  • Error Handling: Automatic status code validation

Available Functions

Core Functions

  • createUrl - Creates URLs with optional query parameters
  • get - Performs GET requests with error handling
  • post - Performs POST requests with JSON payload
  • put - Performs PUT requests with JSON payload

Basic Usage

While you typically won't use the host module directly, understanding its patterns can help with debugging and advanced use cases:

// Internal SDK usage example
const response = await Deno.api.host.get(
    Deno.api.host.createUrl("vrm/all")
);
const vrms = await response.json();

// URL construction with parameters
const url = Deno.api.host.createUrl("gpt/model", {vrm: 123});
// Results in: http://localhost:3100/gpt/model?vrm=123

Error Handling

All host functions automatically validate HTTP response status codes and throw detailed errors for failed requests:

try {
    const response = await Deno.api.host.get(url);
    const data = await response.json();
} catch (error) {
    // Error includes URL, status, and response text
    console.error('Request failed:', error.message);
}

Internal Architecture

The host module serves as the foundation layer for all SDK communication:

  1. URL Construction: Builds properly formatted API endpoints
  2. Request Headers: Sets appropriate content types and headers
  3. Error Detection: Validates response status codes
  4. Type Safety: Ensures consistent response handling

When to Use Direct Host Access

You might need direct host access in these scenarios:

  • Custom API Endpoints: Accessing undocumented or experimental endpoints
  • Raw Response Data: When you need the raw Response object
  • Advanced Error Handling: Custom error processing requirements
  • Performance Optimization: Bypassing higher-level abstractions