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()
From another terminal:
From a third terminal:
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()
From another terminal:
From a third terminal:
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
"""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.