Gateway Call

Gateway Call Interface: Detailed Tutorial

This page focuses on mosaic gateway call: request shape, JSON contract, error handling, and automation patterns.

1. Bring gateway to running state

mosaic --project-state gateway install --host 127.0.0.1 --port 8787
mosaic --project-state gateway start
mosaic --project-state gateway probe

2. Minimal method call

mosaic --project-state gateway call status

This forwards method status with empty params.

3. Method call with JSON params

mosaic --project-state gateway call status --params '{"detail":true}'

--params must be valid JSON object/array/string accepted by the target method.

4. Machine-readable contract

mosaic --project-state --json gateway call status

Current success envelope example:

{
  "ok": true,
  "method": "status",
  "request_id": "...",
  "gateway": { "host": "127.0.0.1", "port": 8787 },
  "data": { "ok": true, "service": "mosaic-gateway", "uptime_seconds": 12 }
}

5. Probe + call runbook pattern

mosaic --project-state --json gateway probe
mosaic --project-state --json gateway call status
mosaic --project-state --json gateway health --verbose

Use this sequence in CI or cron jobs before running dependent automation.

6. Error handling strategy

• If probe fails, do gateway restart then re-run probe.
• If call returns protocol/network errors, inspect logs --tail.
• For persistent failures, run doctor and verify state directory permissions.

7. Restart and shutdown routines

mosaic --project-state gateway restart
mosaic --project-state gateway status --deep
mosaic --project-state gateway stop

8. Automation examples

# shell automation (exit non-zero when call fails)
set -e
mosaic --project-state --json gateway probe >/tmp/gw-probe.json
mosaic --project-state --json gateway call status >/tmp/gw-status.json