Core API Reference

Complete reference for all types, methods, status codes, and function pointers available to modules. Include one header: portal/portal.h

1. Types

portal_header_t — Key-Value Pair

The fundamental unit for message metadata. Headers carry auxiliary information alongside the body.

typedef struct {
    char *key;
    char *value;
} portal_header_t;

portal_labels_t — Label Set

Labels control access to paths. A path can require one or more labels; only authenticated users (or modules) whose token carries matching labels can reach it.

typedef struct {
    char  labels[PORTAL_MAX_LABELS][PORTAL_MAX_LABEL_LEN];
    int   count;
} portal_labels_t;

portal_msg_t — The Universal Message

Every request, command, event, and subscription flows through this single structure. This is Law 2 in code.

typedef struct {
    uint64_t          id;
    char             *path;
    uint8_t           method;
    uint16_t          header_count;
    portal_header_t  *headers;
    void             *body;
    size_t            body_len;
    portal_ctx_t     *ctx;    // auth + trace
} portal_msg_t;

portal_resp_t — Response

Returned by synchronous send calls. Carries a status code, optional headers, and a body.

typedef struct {
    uint16_t          status;
    uint16_t          header_count;
    portal_header_t  *headers;
    void             *body;
    size_t            body_len;
} portal_resp_t;

portal_ctx_t — Message Context

Attached to every message. Carries authentication credentials and distributed tracing information. The core populates this automatically — modules read it but never forge it.

typedef struct {
    portal_auth_t   auth;     // user + token + labels
    portal_trace_t  trace;    // trace_id, parent_id, timestamp_us, hops
    char           *source_node;
    char           *source_module;
} portal_ctx_t;

2. Methods

Seven methods cover every possible interaction pattern. Each message carries exactly one.

3. Status Codes

Inspired by HTTP but reduced to the essentials. Every response carries exactly one status code.

4. Core API (portal_core_t)

Every module receives a portal_core_t pointer on load. This is the module's only interface to the system. All interaction with the core, other modules, events, storage, and configuration goes through these function pointers.

Path Management

Message Routing

Module Queries

Event Loop

Events

Pub/Sub

Storage

Config

Logging

Log levels:

Resource Locking

Physical resources (serial ports, GPIO, IoT devices) require exclusive access. These functions implement Law 14 — auto-lock on first write, keepalive, auto-release after inactivity.

5. Constants

Limits

Access Modes

6. Internal Core Paths

The core registers these paths on startup. They are always available, even with no modules loaded.

/core — Core Status

/auth — Authentication

/users — User Management

/groups — Group Management

/events — Event Registry

7. Communication Patterns

Request / Response

The standard synchronous pattern. A module sends a message and blocks until the target module responds. Used for GET, SET, CALL, and META.

portal_msg_t  *msg  = portal_msg_alloc();
portal_resp_t *resp = portal_resp_alloc();

portal_msg_set_path(msg, "/local/db/users/1");
portal_msg_set_method(msg, PORTAL_METHOD_GET);

int rc = core->send(core, msg, resp);

if (rc == PORTAL_OK && resp->status == PORTAL_OK) {
    // resp->body contains the user record
    process_user(resp->body, resp->body_len);
}

portal_msg_free(msg);
portal_resp_free(resp);

Fire and Forget (Events)

An event producer emits data to a path. All subscribers receive it asynchronously. The producer does not wait and does not know who (or if anyone) received it. Used with PORTAL_METHOD_EVENT.

// Producer: emit an event
const char *payload = "{\"temp\":22.5,\"unit\":\"C\"}";
core->event_emit(core, "/local/iot/sensor/temperature",
                 payload, strlen(payload));

// Consumer: subscribe to events (registered once, usually in module_load)
static void on_temperature(const char *path,
                            const void *data, size_t len,
                            void *userdata) {
    core->log(core, PORTAL_LOG_INFO, "dashboard",
              "temperature update: %.*s", (int)len, (const char *)data);
}

core->subscribe(core, "/local/iot/sensor/*", on_temperature, NULL);