aamio-lan 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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AI SENSE AS
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,71 @@
1
+ Metadata-Version: 2.4
2
+ Name: aamio-lan
3
+ Version: 0.1.0
4
+ Summary: aamio over the local network: a transport under contract 3 that sends each frame as one UDP datagram, to an address or to everyone on the network.
5
+ Author: AI SENSE AS
6
+ License: MIT
7
+ Project-URL: Homepage, https://aamio.at/docs/addons
8
+ Project-URL: Source, https://github.com/aisenseapi/aamio-python/tree/main/addons/lan
9
+ Project-URL: Changelog, https://github.com/aisenseapi/aamio-python/blob/main/addons/lan/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/aisenseapi/aamio-python/issues
11
+ Keywords: aamio,agents,transport,lan,udp
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: aamio>=0.7.0
16
+ Dynamic: license-file
17
+
18
+ # aamio-lan
19
+
20
+ aamio over the local network: a transport under contract 3 that sends each
21
+ frame as one UDP datagram. Two machines on the same network can then exchange
22
+ aamio messages directly, also when aamio.at cannot be reached.
23
+
24
+ The transport is a dumb pipe. The core seals each message for its recipient,
25
+ signs it, counts it and receipts it (part A of contract 3); the transport only
26
+ moves frames. Everyone on the network can see that frames go, how big they
27
+ are, and the four-byte hints in them, and anyone there can send frames, which
28
+ the core then verifies and refuses when they are not from a partner.
29
+
30
+ ## Use
31
+
32
+ ```bash
33
+ pip install aamio-lan
34
+ aamio addon enable lan
35
+ aamio partner add NAME KEY
36
+ aamio transport bind NAME lan
37
+ ```
38
+
39
+ aamio-lan needs aamio 0.7.0 or later. From then on a message to that partner
40
+ goes over the local network, and never over HTTPS instead. The partner binds
41
+ your key the same way. Only the process that owns the home runs the transport:
42
+ `aamio serve`, and `aamio send` or `aamio read --wait` while they run.
43
+
44
+ ## Settings
45
+
46
+ The manifest declares these variables, and the core passes them on:
47
+
48
+ | Variable | Meaning |
49
+ |---|---|
50
+ | `AAMIO_LAN_PORT` | the UDP port this transport listens on, 47474 if left out |
51
+ | `AAMIO_LAN_BIND` | the address it listens on, 0.0.0.0 if left out |
52
+ | `AAMIO_LAN_BROADCAST` | where a frame to nobody in particular goes, 255.255.255.255 if left out, `none` for nowhere |
53
+ | `AAMIO_LAN_PEERS` | host:port of other transports it also sends such frames to, comma separated |
54
+
55
+ An address is `lan:<ip>:<port>`. A frame to nobody in particular, as the first
56
+ ask to a partner whose address is not known yet, goes to the broadcast address
57
+ and to the peers; after that the core answers the address a verified envelope
58
+ came from. Where broadcast does not reach, as on a guest network that keeps
59
+ devices apart, name the other machine in `AAMIO_LAN_PEERS`.
60
+
61
+ ## On the wire
62
+
63
+ Each datagram is `AL1`, eight random bytes that name the transport process,
64
+ and one frame of contract 3 (A8), at most 1200 bytes, so a datagram stays well
65
+ inside one Ethernet packet. A transport drops datagrams it sent itself, which a
66
+ broadcast brings back, and anything that does not start with `AL1`. The same
67
+ datagrams are sent by the LAN transports of aamio-php and aamio-js, so any of
68
+ them can talk to any other.
69
+
70
+ What a transport is, and how to write one, is at
71
+ https://aamio.at/docs/addons#transports.
@@ -0,0 +1,54 @@
1
+ # aamio-lan
2
+
3
+ aamio over the local network: a transport under contract 3 that sends each
4
+ frame as one UDP datagram. Two machines on the same network can then exchange
5
+ aamio messages directly, also when aamio.at cannot be reached.
6
+
7
+ The transport is a dumb pipe. The core seals each message for its recipient,
8
+ signs it, counts it and receipts it (part A of contract 3); the transport only
9
+ moves frames. Everyone on the network can see that frames go, how big they
10
+ are, and the four-byte hints in them, and anyone there can send frames, which
11
+ the core then verifies and refuses when they are not from a partner.
12
+
13
+ ## Use
14
+
15
+ ```bash
16
+ pip install aamio-lan
17
+ aamio addon enable lan
18
+ aamio partner add NAME KEY
19
+ aamio transport bind NAME lan
20
+ ```
21
+
22
+ aamio-lan needs aamio 0.7.0 or later. From then on a message to that partner
23
+ goes over the local network, and never over HTTPS instead. The partner binds
24
+ your key the same way. Only the process that owns the home runs the transport:
25
+ `aamio serve`, and `aamio send` or `aamio read --wait` while they run.
26
+
27
+ ## Settings
28
+
29
+ The manifest declares these variables, and the core passes them on:
30
+
31
+ | Variable | Meaning |
32
+ |---|---|
33
+ | `AAMIO_LAN_PORT` | the UDP port this transport listens on, 47474 if left out |
34
+ | `AAMIO_LAN_BIND` | the address it listens on, 0.0.0.0 if left out |
35
+ | `AAMIO_LAN_BROADCAST` | where a frame to nobody in particular goes, 255.255.255.255 if left out, `none` for nowhere |
36
+ | `AAMIO_LAN_PEERS` | host:port of other transports it also sends such frames to, comma separated |
37
+
38
+ An address is `lan:<ip>:<port>`. A frame to nobody in particular, as the first
39
+ ask to a partner whose address is not known yet, goes to the broadcast address
40
+ and to the peers; after that the core answers the address a verified envelope
41
+ came from. Where broadcast does not reach, as on a guest network that keeps
42
+ devices apart, name the other machine in `AAMIO_LAN_PEERS`.
43
+
44
+ ## On the wire
45
+
46
+ Each datagram is `AL1`, eight random bytes that name the transport process,
47
+ and one frame of contract 3 (A8), at most 1200 bytes, so a datagram stays well
48
+ inside one Ethernet packet. A transport drops datagrams it sent itself, which a
49
+ broadcast brings back, and anything that does not start with `AL1`. The same
50
+ datagrams are sent by the LAN transports of aamio-php and aamio-js, so any of
51
+ them can talk to any other.
52
+
53
+ What a transport is, and how to write one, is at
54
+ https://aamio.at/docs/addons#transports.
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ # A transport under contract 3: aamio over the local network, each frame one
7
+ # UDP datagram. A distribution of its own: `pip install aamio-lan` brings it, and
8
+ # `pip install aamio` alone does not. It lives in the aamio-python repository and
9
+ # is tested with the core, and the core finds it through the entry point below.
10
+ name = "aamio-lan"
11
+ dynamic = ["version"]
12
+ description = "aamio over the local network: a transport under contract 3 that sends each frame as one UDP datagram, to an address or to everyone on the network."
13
+ readme = "README.md"
14
+ requires-python = ">=3.10"
15
+ license = { text = "MIT" }
16
+ authors = [{ name = "AI SENSE AS" }]
17
+ # The first core that knows contract 3. The transport itself needs nothing but the
18
+ # standard library.
19
+ dependencies = ["aamio>=0.7.0"]
20
+ keywords = ["aamio", "agents", "transport", "lan", "udp"]
21
+
22
+ [project.urls]
23
+ Homepage = "https://aamio.at/docs/addons"
24
+ Source = "https://github.com/aisenseapi/aamio-python/tree/main/addons/lan"
25
+ Changelog = "https://github.com/aisenseapi/aamio-python/blob/main/addons/lan/CHANGELOG.md"
26
+ Issues = "https://github.com/aisenseapi/aamio-python/issues"
27
+
28
+ [project.entry-points."aamio.addons"]
29
+ lan = "aamio_lan"
30
+
31
+ [tool.setuptools.dynamic]
32
+ version = { attr = "aamio_lan.__version__" }
33
+
34
+ [tool.setuptools.packages.find]
35
+ where = ["src"]
36
+
37
+ [tool.setuptools.package-data]
38
+ aamio_lan = ["aamio-addon.json"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """aamio over the local network: a transport under contract 3 (see transport.py and aamio-addon.json)."""
2
+
3
+ NAME = "lan"
4
+ __version__ = "0.1.0"
@@ -0,0 +1,13 @@
1
+ {
2
+ "aamio_addon": 3,
3
+ "name": "lan",
4
+ "version": "0.1.0",
5
+ "description": "aamio over the local network: each frame one UDP datagram, to an address or to everyone on the network. The core seals and verifies; the network sees that frames go.",
6
+ "transport": {
7
+ "medium": "lan",
8
+ "start": {"python": "aamio_lan.transport", "php": "transport.php", "node": "transport.js"},
9
+ "platforms": ["linux", "darwin", "win32"],
10
+ "permissions": ["network_local"]
11
+ },
12
+ "environment": ["AAMIO_LAN_PORT", "AAMIO_LAN_BIND", "AAMIO_LAN_BROADCAST", "AAMIO_LAN_PEERS"]
13
+ }
@@ -0,0 +1,191 @@
1
+ """aamio over the local network: a transport under contract 3 that sends each frame as one UDP datagram.
2
+
3
+ A frame to nobody in particular goes to the broadcast address of the network
4
+ and to the peers named in AAMIO_LAN_PEERS, the way everyone on the network can
5
+ hear it; a frame to an address goes to that address alone. An address is
6
+ lan:<ip>:<port>. Each datagram is "AL1", eight bytes that name this process,
7
+ and the frame: a transport drops what it sent itself, which a broadcast brings
8
+ back to it, and anything that is not of this kind. The transport encrypts and
9
+ checks nothing: the core seals and verifies (contract 3, part A). Everyone on
10
+ the network can see that frames go, how big they are and the hints in them.
11
+
12
+ The port is opened after hello, and never when hello says probe: enable then
13
+ only sees that this starts and describes itself. A port that cannot be opened,
14
+ as one another program holds, is said as down and tried again every two
15
+ seconds, and said as up with room once it opens.
16
+
17
+ AAMIO_LAN_PORT the UDP port this transport listens on, 47474 if left out
18
+ AAMIO_LAN_BIND the address it listens on, 0.0.0.0 if left out
19
+ AAMIO_LAN_BROADCAST where a frame to nobody in particular goes, 255.255.255.255 if left out, none for nowhere
20
+ AAMIO_LAN_PEERS host:port of other transports it also sends such frames to, comma separated
21
+ """
22
+
23
+ import base64
24
+ import json
25
+ import os
26
+ import socket
27
+ import sys
28
+ import threading
29
+ import time
30
+
31
+ NAME, VERSION = "lan", "0.1.0"
32
+ MAGIC = b"AL1"
33
+ CREDIT = 32
34
+ MAX_FRAME = 1200
35
+ PORT = 47474
36
+ RETRY_SECONDS = 2.0
37
+
38
+
39
+ def peers_of(text):
40
+ """host:port, comma separated: the ones that cannot be read are said on standard error and left out."""
41
+ found = []
42
+ for part in (text or "").split(","):
43
+ part = part.strip()
44
+ if not part:
45
+ continue
46
+ host, _, port = part.rpartition(":")
47
+ try:
48
+ found.append((socket.gethostbyname(host), int(port)))
49
+ except (OSError, ValueError):
50
+ print("aamio-lan: %r is no host:port, and is left out" % part, file=sys.stderr, flush=True)
51
+ return found
52
+
53
+
54
+ class Lan:
55
+ def __init__(self):
56
+ self.port = int(os.environ.get("AAMIO_LAN_PORT", PORT))
57
+ self.bind = os.environ.get("AAMIO_LAN_BIND", "0.0.0.0")
58
+ broadcast = os.environ.get("AAMIO_LAN_BROADCAST", "255.255.255.255").strip()
59
+ self.broadcast = None if broadcast.lower() in ("", "none") else broadcast
60
+ self.peers = peers_of(os.environ.get("AAMIO_LAN_PEERS", ""))
61
+ self.me = os.urandom(8)
62
+ self.out = threading.Lock()
63
+ self.stopping = False
64
+ self.sends_read = 0
65
+ self.socket = None
66
+
67
+ def _open(self):
68
+ sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
69
+ try:
70
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
71
+ sock.bind((self.bind, self.port))
72
+ except OSError:
73
+ sock.close()
74
+ raise
75
+ return sock
76
+
77
+ def hear(self):
78
+ """Open the port, say ready, and listen; while it cannot be opened, say down once and try again."""
79
+ said_down = False
80
+ while not self.stopping:
81
+ try:
82
+ sock = self._open()
83
+ except OSError as error:
84
+ if not said_down:
85
+ self.say({"t": "status", "state": "down", "reason": "port %d on %s could not be opened: %s" % (self.port, self.bind, error)})
86
+ said_down = True
87
+ time.sleep(RETRY_SECONDS)
88
+ continue
89
+ self.socket = sock
90
+ if said_down:
91
+ self.say({"t": "status", "state": "up", "reason": "port %d is open" % self.port})
92
+ self.say({"t": "ready", "credit": CREDIT, "sends_read": self.sends_read})
93
+ self.listen()
94
+ return
95
+
96
+ def say(self, message):
97
+ line = json.dumps(message, separators=(",", ":")) + "\n"
98
+ with self.out:
99
+ sys.stdout.write(line)
100
+ sys.stdout.flush()
101
+
102
+ def listen(self):
103
+ while True:
104
+ try:
105
+ data, (host, port) = self.socket.recvfrom(65_535)
106
+ except ConnectionResetError:
107
+ # Windows answers a datagram to a port nobody listens on with an error on the next receive. On the
108
+ # network a datagram that finds nobody is just gone, and listening goes on.
109
+ continue
110
+ except OSError as error:
111
+ if self.stopping:
112
+ return
113
+ # A transport that can no longer hear says so (B3), rather than go quiet as if the network were.
114
+ self.say({"t": "status", "state": "down", "reason": "the network cannot be heard: %s" % error})
115
+ return
116
+ if len(data) < len(MAGIC) + 8 + 10 or not data.startswith(MAGIC) or data[3:11] == self.me:
117
+ continue
118
+ frame = data[11:]
119
+ if len(frame) > MAX_FRAME:
120
+ continue
121
+ self.say({"t": "received", "from": "lan:%s:%d" % (host, port), "frame": base64.urlsafe_b64encode(frame).decode("ascii").rstrip("=")})
122
+
123
+ def targets(self, to):
124
+ if to is not None:
125
+ _, host, port = to.split(":", 2)
126
+ return [(host, int(port))]
127
+ found = list(self.peers)
128
+ if self.broadcast is not None:
129
+ found.append((self.broadcast, self.port))
130
+ return found
131
+
132
+ def send(self, message):
133
+ frame = base64.urlsafe_b64decode(message["frame"] + "=" * (-len(message["frame"]) % 4))
134
+ if self.socket is None:
135
+ return {"t": "error", "id": message["id"], "code": "down", "message": "the port is not open"}
136
+ if len(frame) > MAX_FRAME:
137
+ return {"t": "error", "id": message["id"], "code": "too_large", "message": "the frame is larger than %d bytes" % MAX_FRAME}
138
+ to = message.get("to")
139
+ try:
140
+ targets = self.targets(to)
141
+ except (ValueError, IndexError):
142
+ return {"t": "error", "id": message["id"], "code": "bad_address", "message": "an address is lan:<ip>:<port>"}
143
+ if not targets:
144
+ return {"t": "error", "id": message["id"], "code": "nowhere", "message": "no broadcast and no peers: a frame to nobody in particular has nowhere to go"}
145
+ datagram = MAGIC + self.me + frame
146
+ sent = 0
147
+ for target in targets:
148
+ try:
149
+ self.socket.sendto(datagram, target)
150
+ sent += 1
151
+ except OSError as error:
152
+ print("aamio-lan: a frame to %s:%d did not go: %s" % (target[0], target[1], error), file=sys.stderr, flush=True)
153
+ if sent == 0:
154
+ return {"t": "error", "id": message["id"], "code": "send_failed", "message": "the frame could not be given to the network"}
155
+ return {"t": "sent", "id": message["id"]}
156
+
157
+ def run(self):
158
+ for line in sys.stdin:
159
+ message = json.loads(line)
160
+ kind = message.get("t")
161
+ if kind == "hello":
162
+ self.say({"t": "describe", "name": NAME, "version": VERSION, "aamio_addon": 3, "medium": "lan",
163
+ "properties": {"max_frame_up": MAX_FRAME, "max_frame_down": MAX_FRAME, "rate_up": 1_000_000, "rate_down": 1_000_000,
164
+ "direction": "duplex", "addressing": "device", "link_ack": False, "airtime": None,
165
+ "metadata_visible_to": "range", "medium_encrypts": False}})
166
+ if not message.get("probe"):
167
+ threading.Thread(target=self.hear, daemon=True).start()
168
+ elif kind == "send":
169
+ self.sends_read += 1
170
+ self.say(self.send(message))
171
+ self.say({"t": "ready", "credit": CREDIT, "sends_read": self.sends_read})
172
+ elif kind == "cancel":
173
+ pass # a datagram is on the network as soon as it is given, so nothing is left to cancel
174
+ elif kind == "stop":
175
+ break
176
+ self.stopping = True
177
+ if self.socket is not None:
178
+ self.socket.close()
179
+
180
+
181
+ def main():
182
+ try:
183
+ lan = Lan()
184
+ except ValueError as error:
185
+ print("aamio-lan: AAMIO_LAN_PORT is no port: %s" % error, file=sys.stderr, flush=True)
186
+ sys.exit(1)
187
+ lan.run()
188
+
189
+
190
+ if __name__ == "__main__":
191
+ main()
@@ -0,0 +1,71 @@
1
+ Metadata-Version: 2.4
2
+ Name: aamio-lan
3
+ Version: 0.1.0
4
+ Summary: aamio over the local network: a transport under contract 3 that sends each frame as one UDP datagram, to an address or to everyone on the network.
5
+ Author: AI SENSE AS
6
+ License: MIT
7
+ Project-URL: Homepage, https://aamio.at/docs/addons
8
+ Project-URL: Source, https://github.com/aisenseapi/aamio-python/tree/main/addons/lan
9
+ Project-URL: Changelog, https://github.com/aisenseapi/aamio-python/blob/main/addons/lan/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/aisenseapi/aamio-python/issues
11
+ Keywords: aamio,agents,transport,lan,udp
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: aamio>=0.7.0
16
+ Dynamic: license-file
17
+
18
+ # aamio-lan
19
+
20
+ aamio over the local network: a transport under contract 3 that sends each
21
+ frame as one UDP datagram. Two machines on the same network can then exchange
22
+ aamio messages directly, also when aamio.at cannot be reached.
23
+
24
+ The transport is a dumb pipe. The core seals each message for its recipient,
25
+ signs it, counts it and receipts it (part A of contract 3); the transport only
26
+ moves frames. Everyone on the network can see that frames go, how big they
27
+ are, and the four-byte hints in them, and anyone there can send frames, which
28
+ the core then verifies and refuses when they are not from a partner.
29
+
30
+ ## Use
31
+
32
+ ```bash
33
+ pip install aamio-lan
34
+ aamio addon enable lan
35
+ aamio partner add NAME KEY
36
+ aamio transport bind NAME lan
37
+ ```
38
+
39
+ aamio-lan needs aamio 0.7.0 or later. From then on a message to that partner
40
+ goes over the local network, and never over HTTPS instead. The partner binds
41
+ your key the same way. Only the process that owns the home runs the transport:
42
+ `aamio serve`, and `aamio send` or `aamio read --wait` while they run.
43
+
44
+ ## Settings
45
+
46
+ The manifest declares these variables, and the core passes them on:
47
+
48
+ | Variable | Meaning |
49
+ |---|---|
50
+ | `AAMIO_LAN_PORT` | the UDP port this transport listens on, 47474 if left out |
51
+ | `AAMIO_LAN_BIND` | the address it listens on, 0.0.0.0 if left out |
52
+ | `AAMIO_LAN_BROADCAST` | where a frame to nobody in particular goes, 255.255.255.255 if left out, `none` for nowhere |
53
+ | `AAMIO_LAN_PEERS` | host:port of other transports it also sends such frames to, comma separated |
54
+
55
+ An address is `lan:<ip>:<port>`. A frame to nobody in particular, as the first
56
+ ask to a partner whose address is not known yet, goes to the broadcast address
57
+ and to the peers; after that the core answers the address a verified envelope
58
+ came from. Where broadcast does not reach, as on a guest network that keeps
59
+ devices apart, name the other machine in `AAMIO_LAN_PEERS`.
60
+
61
+ ## On the wire
62
+
63
+ Each datagram is `AL1`, eight random bytes that name the transport process,
64
+ and one frame of contract 3 (A8), at most 1200 bytes, so a datagram stays well
65
+ inside one Ethernet packet. A transport drops datagrams it sent itself, which a
66
+ broadcast brings back, and anything that does not start with `AL1`. The same
67
+ datagrams are sent by the LAN transports of aamio-php and aamio-js, so any of
68
+ them can talk to any other.
69
+
70
+ What a transport is, and how to write one, is at
71
+ https://aamio.at/docs/addons#transports.
@@ -0,0 +1,12 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/aamio_lan/__init__.py
5
+ src/aamio_lan/aamio-addon.json
6
+ src/aamio_lan/transport.py
7
+ src/aamio_lan.egg-info/PKG-INFO
8
+ src/aamio_lan.egg-info/SOURCES.txt
9
+ src/aamio_lan.egg-info/dependency_links.txt
10
+ src/aamio_lan.egg-info/entry_points.txt
11
+ src/aamio_lan.egg-info/requires.txt
12
+ src/aamio_lan.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [aamio.addons]
2
+ lan = aamio_lan
@@ -0,0 +1 @@
1
+ aamio>=0.7.0
@@ -0,0 +1 @@
1
+ aamio_lan