Skip to content

6.1 REST API Endpoints

Jump to bottom
Raul Cardenas Montoya edited this page Sep 19, 2026 · 2 revisions

REST API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

The corpus_ipc_server binary provides a RESTful interface to the corpus-ipc crate, allowing remote clients to interact with an IpcBackend over HTTP src/bin/corpus_ipc_server.rs:3-15. Built using the Axum framework, the server exposes four primary POST endpoints that map directly to underlying IpcBackend trait methods src/bin/corpus_ipc_server.rs:45-51.

Purpose and Scope

The HTTP server acts as a thin wrapper around a SharedBackend, defined as an Arc<Mutex<Box<dyn IpcBackend>>> src/bin/corpus_ipc_server.rs:19-19. It handles JSON serialization/deserialization, thread-safe access control via mutexes, routing, and error mapping, enabling language-agnostic access to neural processing capabilities.

Sources:

System Architecture and Data Flow

The following diagrams illustrate how an incoming HTTP request is routed through the Axum server to the underlying backend implementation, bridging the Natural Language Space to the Code Entity Space.

Request Processing Pipeline

graph TD
    subgraph "NaturalLanguageSpace"
        A["HttpClient"]
    end

    subgraph "CodeEntitySpace_Server"
        B["axumRouter"]
        C["SharedBackend"]
        D1["initializeHandler"]
        D2["processHandler"]
        D3["saveStateHandler"]
        D4["resetHandler"]
        E["replyHelper"]
    end

    subgraph "CodeEntitySpace_Trait"
        F["IpcBackendTrait"]
    end

    subgraph "BackendImplementations"
        G["RustBackend"]
        H["ZmqIpcBackend"]
    end

    A -- "POST /process" --> B
    B -- "extractsExtension" --> C
    B -- "routesTo" --> D2
    D2 -- "lockUnwrap" --> C
    D2 -- "processBatch" --> F
    F -. "implementation" .-> G
    F -. "implementation" .-> H
    F -- "ResultVecf32BackendError" --> D2
    D2 -- "mapsToJson" --> E
    E -- "JsonResponse" --> A
Loading

Sources:

Backend Selection and Initialization Flow

graph TD
    subgraph "EnvironmentConfiguration"
        ENV1["CORPUS_IPC_BACKEND_TYPE"]
        ENV2["CORPUS_IPC_BIND"]
    end

    subgraph "CodeEntitySpace_Main"
        F1["BackendFactoryCreate"]
        S1["SharedBackend"]
        R1["RouterNew"]
    end

    ENV1 -- "readEnv" --> F1
    F1 -- "returnsBoxBackend" --> S1
    S1 -- "ExtensionBackend" --> R1
    ENV2 -- "TcpListenerBind" --> R1
Loading

Sources:

Endpoint Specifications

1. Initialize Backend

Endpoint: POST /initialize

Initializes the active backend, optionally loading a model from a provided path src/bin/corpus_ipc_server.rs:96-103.

Requirement Type Description
Request Body InitializeReq JSON object containing an optional model_path src/bin/corpus_ipc_server.rs:68-71.
Response Body SimpleRes Status of the initialization src/bin/corpus_ipc_server.rs:88-92.

Request Schema (InitializeReq):

{
  "model_path": "string" | null
}

Implementation Logic: The initialize handler extracts the model_path and invokes be.initialize(payload.model_path.as_deref()) src/bin/corpus_ipc_server.rs:96-103.

Sources:

2. Process Batch

Endpoint: POST /process

The primary inference endpoint. It accepts a vector of input signals and returns the processed output signals src/bin/corpus_ipc_server.rs:105-117.

Requirement Type Description
Request Body ProcessReq JSON object containing a vector of f32 src/bin/corpus_ipc_server.rs:74-76.
Response Body ProcessRes JSON object containing the output vector src/bin/corpus_ipc_server.rs:78-81.
Error Body SimpleRes Returned on BackendError with ok: false src/bin/corpus_ipc_server.rs:88-92.

Request Schema (ProcessReq):

{
  "inputs": [0.1, 0.5, -0.2]
}

Response Schema (ProcessRes):

{
  "output": [0.9, 0.1]
}

Implementation Logic: The process handler calls be.process_batch(&payload.inputs) src/bin/corpus_ipc_server.rs:109-110. On success, it wraps the output in ProcessRes src/bin/corpus_ipc_server.rs:111. On failure, it returns a SimpleRes containing the error description src/bin/corpus_ipc_server.rs:112-116.

Sources:

3. Save State

Endpoint: POST /save_state

Triggers the backend to persist its current internal state (weights, configuration, etc.) to the specified file system path src/bin/corpus_ipc_server.rs:119-126.

Requirement Type Description
Request Body SaveStateReq JSON object with a mandatory model_path src/bin/corpus_ipc_server.rs:83-86.
Response Body SimpleRes Status of the save operation src/bin/corpus_ipc_server.rs:88-92.

Request Schema (SaveStateReq):

{
  "model_path": "/path/to/save/model.bin"
}

Sources:

4. Reset

Endpoint: POST /reset

Resets the backend to its initial state, clearing internal buffers or resetting weights depending on the active backend implementation src/bin/corpus_ipc_server.rs:128-136.

Requirement Type Description
Request Body Empty No payload required.
Response Body SimpleRes Status of the reset operation src/bin/corpus_ipc_server.rs:88-92.

Note: After a /reset, some backends (notably ZmqIpcBackend) clear connection state and require a subsequent /initialize call before processing can resume src/bin/corpus_ipc_server.rs:131-135.

Sources:

Response Formats and Error Mapping

SimpleRes Format

Most endpoints (except /process on success) return the SimpleRes structure to indicate the result of the operation src/bin/corpus_ipc_server.rs:88-92.

#[derive(Debug, Serialize)]
struct SimpleRes {
    ok: bool,
    message: String,
}

Sources:

Error Mapping Logic

The server uses a helper function reply() to convert Result<(), BackendError> into the standard SimpleRes JSON format src/bin/corpus_ipc_server.rs:140-151. If a BackendError occurs, the ok field is set to false, and the message field is populated using the error's to_string() implementation src/bin/corpus_ipc_server.rs:146-150.

graph LR
    subgraph "ErrorHandlingLogic"
        direction LR
        E["BackendError"] -- "eToString" --> M["messageString"]
        M --> SR["SimpleResOkFalse"]
    end
Loading

Sources:

Handler Summary Table

Endpoint Handler Function Request Type Success Response
/initialize initialize InitializeReq SimpleRes src/bin/corpus_ipc_server.rs:96-103
/process process ProcessReq ProcessRes src/bin/corpus_ipc_server.rs:105-117
/save_state save_state SaveStateReq SimpleRes src/bin/corpus_ipc_server.rs:119-126
/reset reset N/A SimpleRes src/bin/corpus_ipc_server.rs:128-136

Sources:

corpus-ipc

Clone this wiki locally