Referencia de la API del núcleo

Referencia completa de todos los tipos, métodos, códigos de estado y punteros de función disponibles para los módulos. Incluye un solo header: portal/portal.h

1. Tipos

portal_header_t — Par clave-valor

La unidad fundamental para los metadatos de un mensaje. Los headers transportan información auxiliar junto al body.

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

portal_labels_t — Conjunto de etiquetas

Las etiquetas controlan el acceso a los path. Un path puede requerir una o más etiquetas; solo los usuarios autenticados (o módulos) cuyo token contenga etiquetas coincidentes pueden acceder a él.

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

portal_msg_t — El mensaje universal

Cada petición, comando, evento y suscripción fluye a través de esta única estructura. Esto es la Ley 2 en código.

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 — Respuesta

Devuelta por las llamadas síncronas de send. Contiene un código de estado, headers opcionales y un 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 — Contexto del mensaje

Adjunto a cada mensaje. Contiene las credenciales de autenticación y la información de trazabilidad distribuida. El core lo rellena automáticamente — los módulos lo leen pero nunca lo falsifican.

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. Métodos

Siete métodos cubren todos los patrones de interacción posibles. Cada mensaje lleva exactamente uno.

3. Códigos de estado

Inspirados en HTTP pero reducidos a lo esencial. Cada respuesta lleva exactamente un código de estado.

4. API del core (portal_core_t)

Cada module recibe un puntero portal_core_t al cargarse. Esta es la única interfaz del module con el sistema. Toda interacción con el core, otros módulos, eventos, almacenamiento y configuración pasa a través de estos punteros de función.

Gestión de path

Enrutamiento de mensajes

Consultas de módulos

Event loop

Eventos

Pub/Sub

Almacenamiento

Configuración

Registro de log

Niveles de log:

Bloqueo de recursos

Los recursos físicos (puertos serie, GPIO, dispositivos IoT) requieren acceso exclusivo. Estas funciones implementan la Ley 14 — bloqueo automático en la primera escritura, keepalive y liberación automática tras inactividad.

5. Constantes

Límites

Modos de acceso

6. Path internos del core

El core registra estos path al iniciar. Están siempre disponibles, incluso sin módulos cargados.

/core — Estado del core

/auth — Autenticación

/users — Gestión de usuarios

/groups — Gestión de grupos

/events — Registro de eventos

7. Patrones de comunicación

Petición / Respuesta

El patrón síncrono estándar. Un module envía un mensaje y se bloquea hasta que el module de destino responde. Se utiliza para GET, SET, CALL y 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);

Disparar y olvidar (Eventos)

Un productor de eventos emite datos a un path. Todos los suscriptores los reciben de forma asíncrona. El productor no espera y no sabe quién (o si alguien) los recibió. Se utiliza con 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);