Skip to content

Examples

These three directories are in samples/. Each one is self-contained. Start the helper process, then Switchboard, then the client script. Stop each process with Ctrl-C.

The ports are local and fixed. Do not run two samples that bind the same port at the same time.

Line

samples/line copies a newline-framed TCP message to another TCP port and copies the reply back.

version: 1
bridges:
  - name: line
    mode: gateway
    input:
      protocol: tcp
      host: 127.0.0.1
      port: 19000
      framing:
        type: newline
    output:
      protocol: tcp
      host: 127.0.0.1
      port: 19001
      framing:
        type: newline
"""Send one line through the line sample gateway."""

from __future__ import annotations

import socket

import os

HOST = "127.0.0.1"
PORT = int(os.environ.get("SWITCHBOARD_SEND_PORT", "19000"))


def main() -> None:
    with socket.create_connection((HOST, PORT), timeout=5) as connection:
        connection.sendall(b"hello\n")
        payload = _read_line(connection)
    print(payload.decode().rstrip("\n"))


def _read_line(connection: socket.socket) -> bytes:
    chunks = bytearray()
    while b"\n" not in chunks:
        piece = connection.recv(1024)
        if not piece:
            break
        chunks.extend(piece)
    return bytes(chunks)


if __name__ == "__main__":
    main()
cd samples/line
python echo.py

From another terminal:

cd samples/line
switchboard --config switchboard.yml serve

From a third terminal:

cd samples/line
python send.py

echo.py prints listening, then prints each line it receives and sends that line back. send.py prints hello. The bytes on the wire include the newline. The message Switchboard forwards is the text before that newline, and the output framing adds the newline again.

switchboard --config switchboard.yml config validate checks the file without listening.

Webhook

samples/webhook accepts a POST on /events and writes the body to a TCP line. The HTTP response is forwarded: Switchboard answers after the line has been written, and that answer is not the TCP peer's reply.

version: 1
bridges:
  - name: events
    mode: gateway
    http:
      response: forwarded
      response_status: 202
    input:
      protocol: http
      host: 127.0.0.1
      port: 18081
      path: /events
      method: POST
    output:
      protocol: tcp
      host: 127.0.0.1
      port: 19011
      framing:
        type: newline
"""POST one JSON body through the webhook sample gateway."""

from __future__ import annotations

import os
import urllib.request

URL = os.environ.get("SWITCHBOARD_POST_URL", "http://127.0.0.1:18081/events")


def main() -> None:
    request = urllib.request.Request(
        URL,
        data=b'{"event":"ping"}',
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=5) as response:
        print(response.status)


if __name__ == "__main__":
    main()
cd samples/webhook
python echo.py

From another terminal:

cd samples/webhook
switchboard --config switchboard.yml serve

From a third terminal:

cd samples/webhook
python post.py

post.py prints 202. The echo prints the JSON body and a newline. A response of 202 means the local write finished. It does not mean another system stored the event. If the echo is not listening, the POST fails and Switchboard returns 502.

The same call without the script:

curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" \
  --request POST --data '{"event":"ping"}' \
  http://127.0.0.1:18081/events

Profile

samples/profile describes a three-field structure and does not need a running gateway. kind is one byte, note is four characters, and rest is whatever remains, shown as base64.

version: 1
profiles:
  device:
    transport: tcp
    framing:
      type: length_prefix
      prefix_bytes: 2
      endian: big
    structure:
      endian: big
      fields:
        - name: kind
          type: uint8
        - name: note
          type: string
          length: 4
        - name: rest
          type: remaining_bytes
{"kind": 1, "note": "ping", "rest": ""}
"""Encode and decode the profile sample without starting the gateway."""

from __future__ import annotations

import json
from pathlib import Path

from lupaxa.switchboard.config import load_config
from lupaxa.switchboard.profile import decode_profile, encode_profile


def main() -> None:
    root = Path(__file__).resolve().parent
    config = load_config(root / "switchboard.yml", user_path=None)
    profile = config.profiles["device"]
    message = (root / "message.json").read_text(encoding="utf-8")
    raw = encode_profile(profile, message)
    decoded = json.loads(decode_profile(profile, raw))
    print(json.dumps({"decoded": decoded, "bytes": len(raw)}))


if __name__ == "__main__":
    main()
cd samples/profile
python roundtrip.py
switchboard --config switchboard.yml profile encode device message.json > device.bin
switchboard --config switchboard.yml profile decode device device.bin

roundtrip.py prints JSON with the decoded object and the encoded length. profile encode writes the raw bytes. profile decode prints the same JSON object. Neither command opens a socket.