Controllers

All HTTP endpoints exposed by odoo-sync modules.

---

sync_base

class SyncBaseController

Base HTTP controller for transport-agnostic network endpoints.

Provides the blob-serving endpoints and the authorization guard common to all transport implementations.

CIDs

_serve_blob(cid: str, filename: str = '')

Stream a CID blob to the caller.

Fast path: reads directly from ip.cid.data_raw via Odoo’s native filestore streaming (no RAM copy).

Fallback: if data_raw is empty, calls _action_fetch_content() to pull from the remote host node and cache it, then streams the freshly-stored data_raw.

Content-Disposition is set to filename when given, or the CID string otherwise

blob_content_bearer(cid: str, **_kw)

@http.route('/odoo_sync/v0/blob/<string:cid>', auth='bearer', methods=['GET'])

Stream a CID blob to authenticated remote nodes (bearer token).

blob_content_user(cid: str, filename: str = '', **_kw)

@http.route(['/odoo_sync/blob/<string:cid>', '/odoo_sync/blob/<string:cid>/<string:filename>'], auth='user', methods=['GET'])

Stream a CID blob to local Odoo session users (used by ir.attachment URL fields).

Events

_check_authorization(gateway_only=False)

Verify the request user manages a swarm; return their node.

push_events(payloads=None, **kwargs)

@http.route('/odoo_sync/v0/push', type='jsonrpc', auth='bearer')

Receive a batch of P2P events from any transport and admit them to the ledger.

Each payload in the list is validated and anti-spoofed before being handed off to _sync_push for atomic batch ingestion.

Parameters:

payloads – List of event dicts. Each dict must include from_peer, seqno, topic_name, signature, and data_json.

Returns:

{"status": "admitted", "result": {"batches": N}} on success, or {"error": "..."} when payloads are absent, invalid, or duplicate.

See also

sync_base — Core — full module reference.

---

sync_http

class SyncHttpController

Pull-mode polling endpoint for HTTP peers.

Methods

pull_events(topic_names=None, last_sync=None, **_kw)

@http.route('/odoo_sync/v0/pull', type='jsonrpc', auth='bearer')

Expose pending outbound events for remote HTTP peers operating in pull mode.

Parameters:

• topic_names – List of topic name strings to filter events by. Returns an empty list when omitted or empty.

• last_sync – ISO datetime watermark — only events newer than this timestamp are returned.

Returns:

Dict with two keys:

• events — list of event payload dicts ready for import.

• last_sync — server-side safe sync timestamp the caller should store as its watermark for the next pull request.

See also

sync_http — Network — full module reference.

---

sync_kubo

class SyncKuboController

HTTP controller for the Kubo gateway daemon.

Called by the gateway to push and pull network state in a single round-trip.

Methods

sync_gateway_endpoint(**kwargs)

@http.route('/odoo_sync/v0/gateway', type='jsonrpc', auth='bearer', methods=['POST'])

Unified sync/ack endpoint for the Odoo-Sync Kubo gateway.

Executes a complete two-way state reconciliation in a single HTTP request:

• Security: authenticates the gateway via Bearer token and verifies

  it is actively assigned to an Sync swarm.

• Watermarking: derives a safe last_sync timestamp from the oldest

  active database transaction to prevent data-loss race conditions.

• Push: hands the incoming payload to ip.swarm, which processes

  batched record creations and explicit ID updates inside atomic savepoints.

• Pull: returns the latest routing instructions (topics, node trust

  levels, wanted CIDs, and outbound events) to the gateway.

Parameters:

kwargs –

JSON-RPC payload with keys:

• sync_payload (dict): Grouped actions from the gateway, e.g. {"push": {...}, "update": {...}}.

• last_sync (str): The gateway’s last known sync timestamp.

Returns:

Reconciled state dict with keys:

• push / update: Execution status of the incoming batches.

• pull: New routing and network instructions for the gateway.

• last_sync: New safe watermark for the next sync cycle.

Raises:

AccessError – If the token does not belong to a valid gateway node.

See also

sync_kubo — Network — full module reference.

---

Gateway

FastAPI endpoints exposed by the Python gateway sidecar. All routes are internal — called by Odoo or by Kubo’s libp2p layer, not by external clients.

create_express_app(ipfs_client, odoo_client, bouncer, async_fetch_queue, async_bcast_queue, async_direct_queue, sync_batch_queue)

Create the FastAPI app and inject all live gateway queues into app state.

Parameters:

• ipfs_client – Async Kubo RPC client.

• odoo_client – Synchronous Odoo JSON-RPC client.

• bouncer – Unified firewall for all inbound traffic.

• async_fetch_queue – Priority queue for CIDs to download.

• async_bcast_queue – Queue for broadcast events to publish via PubSub.

• async_direct_queue – Queue for direct (express) P2P events.

• sync_batch_queue – Thread-safe queue shared with the batcher thread.

Returns:

Configured fastapi.FastAPI application instance.

express_fetch(payload: dict, request: Request)

@app.post('/api/express_fetch')

Queue CID strings for immediate high-priority fetching, bypassing the verifier queue.

Called by Odoo when a CID is needed urgently (e.g. a waiting event just arrived). Each CID is inserted at priority 0 — the highest — in the async fetch queue.

Parameters:

payload – JSON body with a cids key containing a list of CID strings.

Returns:

{"status": "queued"}

express_send(request: Request)

@app.post('/api/express_send')

Fire-and-forget webhook from Odoo — routes events by routing_mode.

• broadcast → pushed to async_bcast_queue; the listener echo marks the event as sent.

• direct → pushed to async_direct_queue; the sender marks it sent after the libp2p stream completes.

Raises:

HTTPException – 400 if any event payload is missing required routing keys (id, routing_mode, from_peer, topic_name).

p2p_receive(request: Request, bg_tasks: BackgroundTasks)

@app.post('/api/p2p_receive')

Receive a direct P2P message dialled by a remote Kubo peer.

Passes the envelope through the UnifiedBouncer firewall. Admitted events are queued for immediate sub-second Odoo delivery via a background task; ip.cid references are prioritised at rank 0.

Raises:

HTTPException – 400 if the bouncer rejects the envelope.

route_inbound_event(app_state, odoo_event: dict)

Attempt sub-second delivery. Fall back to batch queue if Odoo is busy.

See also

Gateway — batcher protocol, bouncer pipeline, and CID pipeline.