aisenseapi / aamio-lan
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, so two machines exchange aamio messages directly, also when aamio.at cannot be reached. Used through aamio transport bind PARTNER lan.
Package info
github.com/aisenseapi/aamio-addon-lan
Type:aamio-addon
pkg:composer/aisenseapi/aamio-lan
Requires
- php: >=8.1
- aisenseapi/aamio: >=0.4.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
aamio over the local network: a transport under contract 3 that sends each frame as one UDP datagram. Two machines on the same network can then exchange aamio messages directly, also when aamio.at cannot be reached.
The transport is a dumb pipe. The core seals each message for its recipient, signs it, counts it and receipts it (part A of contract 3); the transport only moves frames. Everyone on the network can see that frames go, how big they are, and the four-byte hints in them, and anyone there can send frames, which the core then verifies and refuses when they are not from a partner.
Use
composer require aisenseapi/aamio-lan aamio addon enable lan aamio partner add NAME KEY aamio transport bind NAME lan
From then on a message to that partner goes over the local network, and never
over HTTPS instead. The partner binds your key the same way. Only the process
that owns the home runs the transport: aamio serve, and aamio send or
aamio read --wait while they run.
Settings
The manifest declares these variables, and the core passes them on:
| Variable | Meaning |
|---|---|
AAMIO_LAN_PORT |
the UDP port this transport listens on, 47474 if left out |
AAMIO_LAN_BIND |
the address it listens on, 0.0.0.0 if left out |
AAMIO_LAN_BROADCAST |
where a frame to nobody in particular goes, 255.255.255.255 if left out, none for nowhere |
AAMIO_LAN_PEERS |
host:port of other transports it also sends such frames to, comma separated |
An address is lan:<ip>:<port>. A frame to nobody in particular, as the first
ask to a partner whose address is not known yet, goes to the broadcast address
and to the peers; after that the core answers the address a verified envelope
came from. Where broadcast does not reach, as on a guest network that keeps
devices apart, name the other machine in AAMIO_LAN_PEERS.
One port, one transport
PHP sets SO_REUSEADDR on every socket it binds. Another program that does the
same, another PHP transport among them, can then bind the same UDP port, and on
Windows any other program can. Each then gets some of what comes, and the
transport cannot see it. Give each aamio on one machine its own
AAMIO_LAN_PORT. A port held by a program that does not reuse addresses, as
the transports of aamio-python and aamio-js do not, is said as down until it
is free, except on Windows.
Windows
A PHP process on Windows cannot wait on its standard input together with the
network, so there the transport runs as two processes of transport.php: one
reads what the core writes and passes it on over a socket on 127.0.0.1, and the
other does the work.
On the wire
Each datagram is AL1, eight random bytes that name the transport process,
and one frame of contract 3 (A8), at most 1200 bytes. A transport drops
datagrams it sent itself, which a broadcast brings back, and anything that does
not start with AL1. The same datagrams are sent by the LAN transports of
aamio-python and aamio-js, so any of them can talk to any other.
What a transport is, and how to write one, is at https://aamio.at/docs/addons#transports.