lupaxa-switchboard 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lupaxa_switchboard-0.1.0/.gitignore +24 -0
- lupaxa_switchboard-0.1.0/LICENCE +21 -0
- lupaxa_switchboard-0.1.0/PKG-INFO +249 -0
- lupaxa_switchboard-0.1.0/README.md +180 -0
- lupaxa_switchboard-0.1.0/docs/README.md +23 -0
- lupaxa_switchboard-0.1.0/pyproject.toml +113 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/__init__.py +7 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/__main__.py +10 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/cli.py +804 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/config.py +1190 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/exceptions.py +40 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/framing.py +264 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/gateway.py +2634 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/log.py +34 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/manage.py +227 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/message.py +56 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/profile.py +300 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/route.py +159 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/router.py +145 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/tls.py +38 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/transform.py +300 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/tui.py +140 -0
- lupaxa_switchboard-0.1.0/src/lupaxa/switchboard/version.py +10 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# OS
|
|
2
|
+
.DS_Store
|
|
3
|
+
|
|
4
|
+
# Cursor
|
|
5
|
+
.cursor/
|
|
6
|
+
.superpowers/
|
|
7
|
+
.worktrees/
|
|
8
|
+
cursor-docs
|
|
9
|
+
|
|
10
|
+
# Make
|
|
11
|
+
.makefiles/
|
|
12
|
+
|
|
13
|
+
# MkDocs
|
|
14
|
+
site/
|
|
15
|
+
|
|
16
|
+
# Python
|
|
17
|
+
.venv/
|
|
18
|
+
__pycache__/
|
|
19
|
+
.mypy_cache/
|
|
20
|
+
.ruff_cache/
|
|
21
|
+
.pytest_cache/
|
|
22
|
+
dist/
|
|
23
|
+
build/
|
|
24
|
+
*.egg-info/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) The Lupaxa Project
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: lupaxa-switchboard
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Connect applications that use different protocols without extra infrastructure.
|
|
5
|
+
Project-URL: Homepage, https://github.com/lupaxa-developers-toolbox/switchboard
|
|
6
|
+
Project-URL: Repository, https://github.com/lupaxa-developers-toolbox/switchboard
|
|
7
|
+
Project-URL: Issues, https://github.com/lupaxa-developers-toolbox/switchboard/issues
|
|
8
|
+
Author: The Lupaxa Project
|
|
9
|
+
License: MIT License
|
|
10
|
+
|
|
11
|
+
Copyright (c) The Lupaxa Project
|
|
12
|
+
|
|
13
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
14
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
15
|
+
in the Software without restriction, including without limitation the rights
|
|
16
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
17
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
18
|
+
furnished to do so, subject to the following conditions:
|
|
19
|
+
|
|
20
|
+
The above copyright notice and this permission notice shall be included in all
|
|
21
|
+
copies or substantial portions of the Software.
|
|
22
|
+
|
|
23
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
24
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
25
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
26
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
27
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
28
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
29
|
+
SOFTWARE.
|
|
30
|
+
License-File: LICENCE
|
|
31
|
+
Keywords: cli,gateway,networking,protocols,switchboard
|
|
32
|
+
Classifier: Development Status :: 3 - Alpha
|
|
33
|
+
Classifier: Environment :: Console
|
|
34
|
+
Classifier: Intended Audience :: Developers
|
|
35
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
36
|
+
Classifier: Operating System :: OS Independent
|
|
37
|
+
Classifier: Programming Language :: Python :: 3
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
42
|
+
Classifier: Topic :: Software Development
|
|
43
|
+
Classifier: Topic :: System :: Networking
|
|
44
|
+
Requires-Python: >=3.11
|
|
45
|
+
Requires-Dist: aiohttp>=3.11
|
|
46
|
+
Requires-Dist: platformdirs>=4
|
|
47
|
+
Requires-Dist: pydantic>=2
|
|
48
|
+
Requires-Dist: pyyaml>=6
|
|
49
|
+
Requires-Dist: rich>=13
|
|
50
|
+
Requires-Dist: typer>=0.12
|
|
51
|
+
Provides-Extra: dev
|
|
52
|
+
Requires-Dist: bump-my-version>=1.2.0; extra == 'dev'
|
|
53
|
+
Requires-Dist: hatch>=1.12.0; extra == 'dev'
|
|
54
|
+
Requires-Dist: hypothesis>=6.100; extra == 'dev'
|
|
55
|
+
Requires-Dist: mypy>=1.12.0; extra == 'dev'
|
|
56
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
|
|
57
|
+
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
|
|
58
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
59
|
+
Requires-Dist: ruff>=0.6.0; extra == 'dev'
|
|
60
|
+
Requires-Dist: textual>=1.0; extra == 'dev'
|
|
61
|
+
Provides-Extra: test
|
|
62
|
+
Requires-Dist: hypothesis>=6.100; extra == 'test'
|
|
63
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
64
|
+
Requires-Dist: pytest-cov>=5.0; extra == 'test'
|
|
65
|
+
Requires-Dist: pytest>=8.0; extra == 'test'
|
|
66
|
+
Provides-Extra: tui
|
|
67
|
+
Requires-Dist: textual>=1.0; extra == 'tui'
|
|
68
|
+
Description-Content-Type: text/markdown
|
|
69
|
+
|
|
70
|
+
<p align="center">
|
|
71
|
+
<a href="https://github.com/lupaxa-developers-toolbox">
|
|
72
|
+
<img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/developers-toolbox/readme-logo.png" alt="Developers Toolbox" />
|
|
73
|
+
</a>
|
|
74
|
+
</p>
|
|
75
|
+
|
|
76
|
+
<h1 align="center">Switchboard</h1>
|
|
77
|
+
|
|
78
|
+
Switchboard connects applications that use different protocols. It runs
|
|
79
|
+
locally and forwards between TCP, UDP, WebSocket, and HTTP endpoints. No
|
|
80
|
+
extra broker or database is required.
|
|
81
|
+
|
|
82
|
+
> **Note:** UDP does not guarantee delivery, ordering, or duplicate
|
|
83
|
+
> suppression. An HTTP `accepted` response means the request was admitted
|
|
84
|
+
> locally, not stored. A process restart drops anything still in flight.
|
|
85
|
+
> A successful local write is not proof that the remote application
|
|
86
|
+
> handled the message. A trace `send` means the local socket accepted the
|
|
87
|
+
> bytes.
|
|
88
|
+
|
|
89
|
+
The PyPI name is `lupaxa-switchboard`. The import path is
|
|
90
|
+
`lupaxa.switchboard`. The console script is `switchboard`. `lupaxa` is a
|
|
91
|
+
namespace package — there is no `lupaxa/__init__.py`.
|
|
92
|
+
|
|
93
|
+
## Install
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pip install lupaxa-switchboard
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Python 3.11 or newer is required.
|
|
100
|
+
|
|
101
|
+
## Example
|
|
102
|
+
|
|
103
|
+
```yaml
|
|
104
|
+
version: 1
|
|
105
|
+
bridges:
|
|
106
|
+
- name: tcp-to-tcp
|
|
107
|
+
mode: gateway
|
|
108
|
+
input:
|
|
109
|
+
protocol: tcp
|
|
110
|
+
host: 127.0.0.1
|
|
111
|
+
port: 9000
|
|
112
|
+
framing:
|
|
113
|
+
type: newline
|
|
114
|
+
output:
|
|
115
|
+
protocol: tcp
|
|
116
|
+
host: 127.0.0.1
|
|
117
|
+
port: 9001
|
|
118
|
+
framing:
|
|
119
|
+
type: newline
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
A gateway bridge can set `forward` and `reverse` pipelines. `forward` runs
|
|
123
|
+
on the way to the output. `reverse` runs on the way back. The endpoint
|
|
124
|
+
framing is still applied after those steps. A field transform is rejected
|
|
125
|
+
when the configuration is loaded unless `json-parse` comes first.
|
|
126
|
+
|
|
127
|
+
TCP endpoints need an explicit framing policy. `raw_stream` is valid only
|
|
128
|
+
when both TCP endpoints use it. A TCP stream and a UDP endpoint can share
|
|
129
|
+
a bridge when the TCP side is framed: each frame is one datagram, and each
|
|
130
|
+
datagram is written back with that framing.
|
|
131
|
+
|
|
132
|
+
## Protocols
|
|
133
|
+
|
|
134
|
+
WebSocket messages already have boundaries, so those endpoints do not take
|
|
135
|
+
a framing block. HTTP inputs answer with `accepted`, `forwarded`, or
|
|
136
|
+
`upstream`. `upstream` is only valid when the output is also HTTP.
|
|
137
|
+
`Authorization`, `Cookie`, and proxy credential headers are not forwarded
|
|
138
|
+
unless `http.forward_headers` names them.
|
|
139
|
+
|
|
140
|
+
TLS is available on TCP, WebSocket, and HTTP. Outbound certificate
|
|
141
|
+
verification stays on unless `tls.verify` is false, which logs a warning.
|
|
142
|
+
Outbound TCP and WebSocket connections can retry with `reconnect`. Payloads
|
|
143
|
+
that were already written are not sent again.
|
|
144
|
+
|
|
145
|
+
## Router
|
|
146
|
+
|
|
147
|
+
`mode: router` treats each framed message on its own. Rules choose named
|
|
148
|
+
outputs. With no rules, every output receives the message. One failed
|
|
149
|
+
destination does not stop the others. `delivery.success` is `all`, `any`,
|
|
150
|
+
or `best_effort`.
|
|
151
|
+
|
|
152
|
+
Transforms are declarative: JSON, fields, text, encoding, and `{{field}}`
|
|
153
|
+
templates. They do not run Python. A buffer limit drops or rejects messages
|
|
154
|
+
instead of storing them. Retries run only when the payload was not sent, or
|
|
155
|
+
when `delivery.retry.replay` is set. Hop count and a static cycle check stop
|
|
156
|
+
obvious forwarding loops.
|
|
157
|
+
|
|
158
|
+
## Profiles
|
|
159
|
+
|
|
160
|
+
A profile names a transport, a framing rule, a character encoding, and an
|
|
161
|
+
optional flat structure. An endpoint can use `profile` instead of repeating
|
|
162
|
+
those settings. The structure is decoded once when a message arrives and
|
|
163
|
+
encoded once when it leaves. Byte fields are base64 in the JSON form.
|
|
164
|
+
Fixed strings are padded with NUL bytes.
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
switchboard profile list
|
|
168
|
+
switchboard profile show device-protocol
|
|
169
|
+
switchboard profile validate profiles.yml
|
|
170
|
+
switchboard profile decode device-protocol sample.bin
|
|
171
|
+
switchboard profile encode device-protocol message.json
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`profile decode` and `profile encode` do not start the gateway.
|
|
175
|
+
|
|
176
|
+
## Management
|
|
177
|
+
|
|
178
|
+
Set `management.enabled` to open a local control socket. Loopback TCP is
|
|
179
|
+
available and requires a token. Bridge listeners do not accept management
|
|
180
|
+
requests.
|
|
181
|
+
|
|
182
|
+
`switchboard status` uses that socket when the process is running. `bridge
|
|
183
|
+
start`, `bridge stop`, `bridge restart`, `connections`, `metrics`, `trace`,
|
|
184
|
+
and `reload` do too. Reload checks the file before it changes anything, and
|
|
185
|
+
leaves an unchanged bridge running. Replacing a listener is not atomic: the
|
|
186
|
+
port can be lost between the stop and the next bind.
|
|
187
|
+
|
|
188
|
+
`switchboard test` reports configuration, a local profile round trip, and a
|
|
189
|
+
TCP connect separately. It does not call that an end-to-end delivery.
|
|
190
|
+
|
|
191
|
+
Traces hide payloads unless `diagnostics.trace_payloads` is true. The
|
|
192
|
+
preview is a short hex string. Names in `diagnostics.secret_fields` are
|
|
193
|
+
replaced before that preview is recorded.
|
|
194
|
+
|
|
195
|
+
`switchboard tui` is optional. Install it with
|
|
196
|
+
`pip install lupaxa-switchboard[tui]`. It only uses the management socket.
|
|
197
|
+
If that socket closes, the screen says it is not connected and drops the
|
|
198
|
+
rows it was showing.
|
|
199
|
+
|
|
200
|
+
## Run
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
switchboard config validate switchboard.yml
|
|
204
|
+
switchboard serve --config switchboard.yml
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
`switchboard bridge list` describes the configuration file. `switchboard
|
|
208
|
+
status` reads the running process when management is enabled.
|
|
209
|
+
|
|
210
|
+
## Samples
|
|
211
|
+
|
|
212
|
+
The repository has three ready-to-run directories under `samples/`.
|
|
213
|
+
This is the smallest. Start the echo:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
cd samples/line
|
|
217
|
+
python echo.py
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
From another terminal, in that same directory:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
switchboard --config switchboard.yml serve
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
From a third terminal, still in `samples/line`:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
python send.py
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`samples/webhook` turns an HTTP POST into a TCP line. `samples/profile`
|
|
233
|
+
encodes and decodes a binary structure without listening.
|
|
234
|
+
|
|
235
|
+
## Documentation
|
|
236
|
+
|
|
237
|
+
The guide lives in `mkdocs/` and publishes to
|
|
238
|
+
<https://switchboard.thelupaxaproject.org/>.
|
|
239
|
+
It has install steps, gateway and router behaviour, a command
|
|
240
|
+
reference, and a walkthrough of each sample with commands you can paste.
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
pip install -r requirements.txt
|
|
244
|
+
mkdocs serve
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
<a href="https://github.com/the-lupaxa-project">
|
|
248
|
+
<img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
|
|
249
|
+
</a>
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/lupaxa-developers-toolbox">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/developers-toolbox/readme-logo.png" alt="Developers Toolbox" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">Switchboard</h1>
|
|
8
|
+
|
|
9
|
+
Switchboard connects applications that use different protocols. It runs
|
|
10
|
+
locally and forwards between TCP, UDP, WebSocket, and HTTP endpoints. No
|
|
11
|
+
extra broker or database is required.
|
|
12
|
+
|
|
13
|
+
> **Note:** UDP does not guarantee delivery, ordering, or duplicate
|
|
14
|
+
> suppression. An HTTP `accepted` response means the request was admitted
|
|
15
|
+
> locally, not stored. A process restart drops anything still in flight.
|
|
16
|
+
> A successful local write is not proof that the remote application
|
|
17
|
+
> handled the message. A trace `send` means the local socket accepted the
|
|
18
|
+
> bytes.
|
|
19
|
+
|
|
20
|
+
The PyPI name is `lupaxa-switchboard`. The import path is
|
|
21
|
+
`lupaxa.switchboard`. The console script is `switchboard`. `lupaxa` is a
|
|
22
|
+
namespace package — there is no `lupaxa/__init__.py`.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install lupaxa-switchboard
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Python 3.11 or newer is required.
|
|
31
|
+
|
|
32
|
+
## Example
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
version: 1
|
|
36
|
+
bridges:
|
|
37
|
+
- name: tcp-to-tcp
|
|
38
|
+
mode: gateway
|
|
39
|
+
input:
|
|
40
|
+
protocol: tcp
|
|
41
|
+
host: 127.0.0.1
|
|
42
|
+
port: 9000
|
|
43
|
+
framing:
|
|
44
|
+
type: newline
|
|
45
|
+
output:
|
|
46
|
+
protocol: tcp
|
|
47
|
+
host: 127.0.0.1
|
|
48
|
+
port: 9001
|
|
49
|
+
framing:
|
|
50
|
+
type: newline
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
A gateway bridge can set `forward` and `reverse` pipelines. `forward` runs
|
|
54
|
+
on the way to the output. `reverse` runs on the way back. The endpoint
|
|
55
|
+
framing is still applied after those steps. A field transform is rejected
|
|
56
|
+
when the configuration is loaded unless `json-parse` comes first.
|
|
57
|
+
|
|
58
|
+
TCP endpoints need an explicit framing policy. `raw_stream` is valid only
|
|
59
|
+
when both TCP endpoints use it. A TCP stream and a UDP endpoint can share
|
|
60
|
+
a bridge when the TCP side is framed: each frame is one datagram, and each
|
|
61
|
+
datagram is written back with that framing.
|
|
62
|
+
|
|
63
|
+
## Protocols
|
|
64
|
+
|
|
65
|
+
WebSocket messages already have boundaries, so those endpoints do not take
|
|
66
|
+
a framing block. HTTP inputs answer with `accepted`, `forwarded`, or
|
|
67
|
+
`upstream`. `upstream` is only valid when the output is also HTTP.
|
|
68
|
+
`Authorization`, `Cookie`, and proxy credential headers are not forwarded
|
|
69
|
+
unless `http.forward_headers` names them.
|
|
70
|
+
|
|
71
|
+
TLS is available on TCP, WebSocket, and HTTP. Outbound certificate
|
|
72
|
+
verification stays on unless `tls.verify` is false, which logs a warning.
|
|
73
|
+
Outbound TCP and WebSocket connections can retry with `reconnect`. Payloads
|
|
74
|
+
that were already written are not sent again.
|
|
75
|
+
|
|
76
|
+
## Router
|
|
77
|
+
|
|
78
|
+
`mode: router` treats each framed message on its own. Rules choose named
|
|
79
|
+
outputs. With no rules, every output receives the message. One failed
|
|
80
|
+
destination does not stop the others. `delivery.success` is `all`, `any`,
|
|
81
|
+
or `best_effort`.
|
|
82
|
+
|
|
83
|
+
Transforms are declarative: JSON, fields, text, encoding, and `{{field}}`
|
|
84
|
+
templates. They do not run Python. A buffer limit drops or rejects messages
|
|
85
|
+
instead of storing them. Retries run only when the payload was not sent, or
|
|
86
|
+
when `delivery.retry.replay` is set. Hop count and a static cycle check stop
|
|
87
|
+
obvious forwarding loops.
|
|
88
|
+
|
|
89
|
+
## Profiles
|
|
90
|
+
|
|
91
|
+
A profile names a transport, a framing rule, a character encoding, and an
|
|
92
|
+
optional flat structure. An endpoint can use `profile` instead of repeating
|
|
93
|
+
those settings. The structure is decoded once when a message arrives and
|
|
94
|
+
encoded once when it leaves. Byte fields are base64 in the JSON form.
|
|
95
|
+
Fixed strings are padded with NUL bytes.
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
switchboard profile list
|
|
99
|
+
switchboard profile show device-protocol
|
|
100
|
+
switchboard profile validate profiles.yml
|
|
101
|
+
switchboard profile decode device-protocol sample.bin
|
|
102
|
+
switchboard profile encode device-protocol message.json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`profile decode` and `profile encode` do not start the gateway.
|
|
106
|
+
|
|
107
|
+
## Management
|
|
108
|
+
|
|
109
|
+
Set `management.enabled` to open a local control socket. Loopback TCP is
|
|
110
|
+
available and requires a token. Bridge listeners do not accept management
|
|
111
|
+
requests.
|
|
112
|
+
|
|
113
|
+
`switchboard status` uses that socket when the process is running. `bridge
|
|
114
|
+
start`, `bridge stop`, `bridge restart`, `connections`, `metrics`, `trace`,
|
|
115
|
+
and `reload` do too. Reload checks the file before it changes anything, and
|
|
116
|
+
leaves an unchanged bridge running. Replacing a listener is not atomic: the
|
|
117
|
+
port can be lost between the stop and the next bind.
|
|
118
|
+
|
|
119
|
+
`switchboard test` reports configuration, a local profile round trip, and a
|
|
120
|
+
TCP connect separately. It does not call that an end-to-end delivery.
|
|
121
|
+
|
|
122
|
+
Traces hide payloads unless `diagnostics.trace_payloads` is true. The
|
|
123
|
+
preview is a short hex string. Names in `diagnostics.secret_fields` are
|
|
124
|
+
replaced before that preview is recorded.
|
|
125
|
+
|
|
126
|
+
`switchboard tui` is optional. Install it with
|
|
127
|
+
`pip install lupaxa-switchboard[tui]`. It only uses the management socket.
|
|
128
|
+
If that socket closes, the screen says it is not connected and drops the
|
|
129
|
+
rows it was showing.
|
|
130
|
+
|
|
131
|
+
## Run
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
switchboard config validate switchboard.yml
|
|
135
|
+
switchboard serve --config switchboard.yml
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`switchboard bridge list` describes the configuration file. `switchboard
|
|
139
|
+
status` reads the running process when management is enabled.
|
|
140
|
+
|
|
141
|
+
## Samples
|
|
142
|
+
|
|
143
|
+
The repository has three ready-to-run directories under `samples/`.
|
|
144
|
+
This is the smallest. Start the echo:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
cd samples/line
|
|
148
|
+
python echo.py
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
From another terminal, in that same directory:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
switchboard --config switchboard.yml serve
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
From a third terminal, still in `samples/line`:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
python send.py
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`samples/webhook` turns an HTTP POST into a TCP line. `samples/profile`
|
|
164
|
+
encodes and decodes a binary structure without listening.
|
|
165
|
+
|
|
166
|
+
## Documentation
|
|
167
|
+
|
|
168
|
+
The guide lives in `mkdocs/` and publishes to
|
|
169
|
+
<https://switchboard.thelupaxaproject.org/>.
|
|
170
|
+
It has install steps, gateway and router behaviour, a command
|
|
171
|
+
reference, and a walkthrough of each sample with commands you can paste.
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
pip install -r requirements.txt
|
|
175
|
+
mkdocs serve
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
<a href="https://github.com/the-lupaxa-project">
|
|
179
|
+
<img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
|
|
180
|
+
</a>
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/lupaxa-developers-toolbox">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/developers-toolbox/readme-logo.png" alt="Organisation Logo" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">Core Documentation</h1>
|
|
8
|
+
|
|
9
|
+
The following documents define the standards that apply across **The Lupaxa Project**:
|
|
10
|
+
|
|
11
|
+
| Document | Purpose |
|
|
12
|
+
| :------------------------------------ | :---------------------------------------------------------------- |
|
|
13
|
+
| [Code of Conduct](CODE_OF_CONDUCT.md) | Expected behaviour and reporting procedures. |
|
|
14
|
+
| [How to Contribute](CONTRIBUTING.md) | Development workflow, coding standards, and contribution process. |
|
|
15
|
+
| [Governance](GOVERNANCE.md) | Project governance, roles, and decision-making. |
|
|
16
|
+
| [Maintainers](MAINTAINERS.md) | Maintainer responsibilities and expectations. |
|
|
17
|
+
| [Projects Overview](PROJECTS.md) | Overview of organisations, repositories, and project structure. |
|
|
18
|
+
| [Security Policy](SECURITY.md) | Responsible disclosure and secure development practices. |
|
|
19
|
+
| [Support Guide](SUPPORT.md) | How to obtain help and support. |
|
|
20
|
+
|
|
21
|
+
<a href="https://github.com/the-lupaxa-project">
|
|
22
|
+
<img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
|
|
23
|
+
</a>
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.18"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "lupaxa-switchboard"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Connect applications that use different protocols without extra infrastructure."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { file = "LICENCE" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "The Lupaxa Project" }
|
|
15
|
+
]
|
|
16
|
+
|
|
17
|
+
keywords = ["switchboard", "gateway", "protocols", "networking", "cli"]
|
|
18
|
+
|
|
19
|
+
dependencies = [
|
|
20
|
+
"aiohttp>=3.11",
|
|
21
|
+
"platformdirs>=4",
|
|
22
|
+
"pydantic>=2",
|
|
23
|
+
"PyYAML>=6",
|
|
24
|
+
"rich>=13",
|
|
25
|
+
"typer>=0.12",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
classifiers = [
|
|
29
|
+
"Development Status :: 3 - Alpha",
|
|
30
|
+
"Environment :: Console",
|
|
31
|
+
"Intended Audience :: Developers",
|
|
32
|
+
"License :: OSI Approved :: MIT License",
|
|
33
|
+
"Operating System :: OS Independent",
|
|
34
|
+
"Programming Language :: Python :: 3",
|
|
35
|
+
"Programming Language :: Python :: 3.11",
|
|
36
|
+
"Programming Language :: Python :: 3.12",
|
|
37
|
+
"Programming Language :: Python :: 3.13",
|
|
38
|
+
"Programming Language :: Python :: 3.14",
|
|
39
|
+
"Topic :: Software Development",
|
|
40
|
+
"Topic :: System :: Networking",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.urls]
|
|
44
|
+
Homepage = "https://github.com/lupaxa-developers-toolbox/switchboard"
|
|
45
|
+
Repository = "https://github.com/lupaxa-developers-toolbox/switchboard"
|
|
46
|
+
Issues = "https://github.com/lupaxa-developers-toolbox/switchboard/issues"
|
|
47
|
+
|
|
48
|
+
[project.scripts]
|
|
49
|
+
switchboard = "lupaxa.switchboard.cli:main"
|
|
50
|
+
|
|
51
|
+
[project.optional-dependencies]
|
|
52
|
+
tui = [
|
|
53
|
+
"textual>=1.0",
|
|
54
|
+
]
|
|
55
|
+
dev = [
|
|
56
|
+
"hypothesis>=6.100",
|
|
57
|
+
"pytest>=8.0",
|
|
58
|
+
"pytest-asyncio>=0.24",
|
|
59
|
+
"pytest-cov>=5.0",
|
|
60
|
+
"ruff>=0.6.0",
|
|
61
|
+
"mypy>=1.12.0",
|
|
62
|
+
"hatch>=1.12.0",
|
|
63
|
+
"bump-my-version>=1.2.0",
|
|
64
|
+
"textual>=1.0",
|
|
65
|
+
]
|
|
66
|
+
test = [
|
|
67
|
+
"hypothesis>=6.100",
|
|
68
|
+
"pytest>=8.0",
|
|
69
|
+
"pytest-asyncio>=0.24",
|
|
70
|
+
"pytest-cov>=5.0",
|
|
71
|
+
]
|
|
72
|
+
|
|
73
|
+
[tool.hatch.version]
|
|
74
|
+
path = "src/lupaxa/switchboard/version.py"
|
|
75
|
+
|
|
76
|
+
[tool.hatch.build.targets.sdist]
|
|
77
|
+
include = [
|
|
78
|
+
"src/**",
|
|
79
|
+
"README.md",
|
|
80
|
+
"LICENCE",
|
|
81
|
+
]
|
|
82
|
+
|
|
83
|
+
[tool.hatch.build.targets.wheel]
|
|
84
|
+
packages = ["src/lupaxa"]
|
|
85
|
+
|
|
86
|
+
[tool.ruff]
|
|
87
|
+
line-length = 100
|
|
88
|
+
target-version = "py311"
|
|
89
|
+
|
|
90
|
+
[tool.ruff.lint]
|
|
91
|
+
select = ["E", "F", "I", "B", "UP", "SIM"]
|
|
92
|
+
|
|
93
|
+
[tool.ruff.format]
|
|
94
|
+
quote-style = "double"
|
|
95
|
+
|
|
96
|
+
[tool.ruff.lint.isort]
|
|
97
|
+
known-first-party = ["lupaxa"]
|
|
98
|
+
|
|
99
|
+
[tool.mypy]
|
|
100
|
+
python_version = "3.11"
|
|
101
|
+
files = ["src", "tests"]
|
|
102
|
+
mypy_path = "src"
|
|
103
|
+
explicit_package_bases = true
|
|
104
|
+
namespace_packages = true
|
|
105
|
+
warn_unused_configs = true
|
|
106
|
+
ignore_missing_imports = true
|
|
107
|
+
|
|
108
|
+
[tool.pytest.ini_options]
|
|
109
|
+
addopts = "-ra -q --disable-warnings"
|
|
110
|
+
testpaths = ["tests"]
|
|
111
|
+
pythonpath = ["src", "."]
|
|
112
|
+
asyncio_mode = "auto"
|
|
113
|
+
asyncio_default_fixture_loop_scope = "function"
|