Flexible ingress
Receive plain UDP over IPv4 or IPv6, or authenticated encrypted UDPSEC station traffic.
AIS stream processing
From receiver traffic to a clean, source-aware feed
AISMixer keeps transport, NMEA assembly, metadata, deduplication, and delivery in one near-real-time processing path.
AIS sentence extraction
Extract both !AIVDM and !AIVDO from realistic receiver and application output.
Multipart assembly
Assemble fully out-of-order fragments into complete logical messages and emit them in ordinal order.
Near-real-time deduplication
Make one group-atomic decision for each complete multipart message, globally in broadcast mode or separately for each routing target.
Controlled TAG metadata
Control NMEA TAG s, c, and g across the multipart lifecycle while keeping metadata separate from routing identity.
Selected forwarding
Forward accepted sentences to every configured UDP output in broadcast mode or to the named targets selected by logical routing.
Campaign D processor boundary
Explicit processing stages and ordered egress
Immutable ingress frames now pass through one ingress fan-in, a processor stage that invokes the synchronous Python reference processor, and one ordered egress stage, all within one process-local supervised lifecycle. Exact lifecycle rules and edge cases remain in the normative behavioural contract.
UDP / UDPSEC producers
Immutable IngressFrame
Ingress fan-in
Queue transport without parsing or routing
PythonDataPlaneProcessor
One snapshot and one synchronous call per accepted frame
Ordered ProcessorOutput batch
Complete tuple before asynchronous egress
Egress stage and UDP targets
Sequential dispatch in tuple order
Immutable ingress boundary
Built-in UDP and UDPSEC producers create immutable IngressFrame objects. Valid legacy IngressEvent objects pass through one compatibility adapter; invalid or unsupported items are rejected before routing-snapshot acquisition and processor invocation.
Synchronous reference processor
DataPlaneProcessor is the explicit contract. PythonDataPlaneProcessor is the sole production and reference implementation; processing remains Python-only and process-local.
One frame, one snapshot
Each accepted frame receives one immutable routing snapshot and one source match, and the processor is invoked exactly once for that frame.
Ordered completion barrier
The complete tuple[ProcessorOutput, ...] is constructed before the first asynchronous send. A non-empty batch prevents later-frame processing until sequential egress completes successfully.
Fail-fast runtime supervision
UDP producers, UDPSEC producers, fan-in, processor, and egress share one process-local lifecycle. Failure or unexpected completion cancels and awaits sibling tasks; there is no automatic restart, retry, rollback, or delivery replay.
Future boundaries remain explicit
Native processing, coordinator/worker processes, multiprocessing, cross-process supervision, and IPC remain future work. Campaign D defines no native API or ABI.
Need the exact edge-case semantics? Read the behavioural contract.
Explicit lifecycle ownership
Deterministic state under load
The reference implementation makes retained state, lifetime progress, capacity admission, cleanup, and observation explicit instead of relying on incidental container behaviour.
Deduplication state
Identity is the exact sentence or ordered multipart tuple, in a global or per-target scope. TTL is deterministic, duplicates do not refresh retention, and expired entries are removed before the oldest live entry is evicted.
The Python object accepts optional max_entries; current service wiring leaves it at None, so this dimension is unbounded in the current service.
Multipart assembly state
Fragments occupy ordinal slots. Unique progress refreshes group lifetime; an exact duplicate does not. Conflict, expiry, capacity removal, completion, and reset remain distinct lifecycle outcomes and clean related TAG context.
The Python object accepts optional max_fragments_per_group and max_pending_groups; current service wiring leaves both at None.
Secure replay and sessions
Handshake replay records, pending sessions, active sessions, and the private nonce state owned by each pending or active session are hard-bounded. Monotonic local time governs TTL, and expired state is removed before deterministic live-state eviction.
Installing a same-address pending candidate preserves the current active session and replaces only an older pending candidate. The active session changes only after authenticated encrypted confirmation and pending-to-active promotion; a failed confirmation, or pending expiry, replacement, or capacity eviction, leaves it intact. All secure state is in-memory, process-local, and lost at restart.
Observable state
Deduplication, assembly, and secure state expose immutable point-in-time statistics for inspection and regression testing. Reading a snapshot does not run cleanup or alter an earlier snapshot.
This is a basis for future differential conformance, not a complete monitoring or Prometheus export system.
Local by design. This state is non-durable and is not shared across processes. The current runtime supervises essential asyncio tasks within one process; coordinator/worker processes, IPC, and cross-process state synchronization do not exist yet.
Reference semantics and staged evolution
A native-ready reference foundation
Campaign C established the immutable, bytes-native ingress representation. Campaign D now defines the synchronous processor contract and explicit single-process runtime boundary, while PythonDataPlaneProcessor remains the sole production and reference implementation.
Immutable ingress representation
Implemented now
Synchronous DataPlaneProcessor contract
Implemented now
PythonDataPlaneProcessor reference
Implemented now
Future differential implementation
Native processor not implemented
Implemented now
Immutable IngressFrame, bytes-native scan spans and parsed metadata, the synchronous processor contract, PythonDataPlaneProcessor, explicit processor and egress stages, and process-local task supervision are implemented.
Future architecture
A native processor and differential conformance execution, coordinator and dedicated ingress/egress worker processes, multiprocessing, IPC and routing-snapshot distribution, and cross-process restart and recovery remain future work.
Boundaries remain explicit
No native processor exists today. No C or C++ API, ABI, or binding strategy has been selected; current supervision remains within one process, and no performance claim is made.
Routing and logical zones
Express stream policy with source identities
Static logical routing connects named ingress sources to named UDP egress targets through reusable source sets and ordered routes.
Named ingressUDP and UDPSEC sources
Logical zonesSets of source identities
Ordered routesDeclarative target selection
Named egressSelected UDP targets
Composable source sets
Define zones with include, union, intersection, and difference.
Logical, not geographic
Zones are sets of internal source identities—not map areas, MMSI filters, vessel filters, or payload rules.
Per-target stream quality
Routing mode scopes deduplication to each logical target, so one delivery path does not suppress another.
source_id is an internal routing identity. It is separate from the NMEA TAG s value emitted downstream.
Runtime routing control
Change active routes without interrupting the data plane
An optional local Unix-domain control plane exposes concise routing operations through the globally installed aismixerctl command.
Inspect routing status
See the active generation, enabled state, logical zones, ordered routes, and target identities.
Replace or disable atomically
Validate a complete candidate before swapping the immutable routing snapshot, or return to legacy broadcast mode.
Reject stale updates
Optional generation checks prevent an operator from overwriting a newer routing change unintentionally.
Deliberately local and process-scoped. Runtime routes are not persisted after restart, configuration files are not rewritten, and ingress or egress adapters are not created dynamically. Unix socket permissions are the current authorization boundary; there is no application-level control token.
Network endpoint controls
Constrain peers and outbound source addresses
Small application-level controls make IPv4 and IPv6 endpoints easier to place inside an operator’s wider firewall and routing policy.
Ingress allow_from
Restrict UDP and UDPSEC listeners to literal IP addresses or CIDR networks, with explicit deny-all behavior available.
Outbound source_ip
Bind an egress socket to a literal IPv4 or IPv6 source address and constrain destination resolution to the same family.
Part of a layered boundary
These policies complement operating-system firewall and routing rules; they do not replace them.
source_ip is source-address binding—not interface selection, routing-table selection, socket marking, or SDN.
UDPSEC lifecycle
Authenticated transport with bounded local state
The current nmea_sproxy and AISMixer UDPSEC path uses authenticated ephemeral ECDHE and independent directional keys, with encrypted sequence-zero confirmation before the client treats a new session as established.
Authenticated ClientHello
Identity-signed, fresh P-256 ephemeral key
Ephemeral P-256 ECDHE
Fresh shared secret for this handshake
HKDF-SHA256
Independent C2S and S2C keys
Encrypted sequence-zero confirmation
C2S ping, then S2C pong
Active session
Authenticated ping promotes; authenticated pong completes
Authenticated ephemeral key agreement
For every session handshake, each endpoint creates a fresh ephemeral P-256 ECDHE keypair. Long-term P-256 identity keys only authenticate canonical, role-separated SHA-256 transcript digests with ECDSA; they are not ECDHE key-agreement inputs.
HKDF-SHA256 derives independent C2S and S2C keys from the shared secret and authenticated transcript. AES-256-GCM protects encrypted data and control traffic.
Encrypted mutual confirmation
The client sends an encrypted sequence-zero ping for the pending session. The server promotes only after authenticating it and returns an encrypted sequence-zero pong under the promoted S2C key; the client treats the session as established only after authenticating that pong.
Unrelated, malformed, stale-key, wrong-sequence, and wrong-source datagrams neither confirm the candidate nor extend its fixed confirmation deadline.
Coordinated update and local state
Both endpoints must be updated together; there is no legacy fallback, mixed mode, negotiation switch, certificate system, or algorithm negotiation.
Allowed traffic drives expiry cleanup rather than a background timer. Replay, pending-session, active-session, and nonce state is in-memory, process-local, non-durable, and lost when the service restarts.
Forward-secrecy boundary: Later compromise of a long-term identity key does not by itself reconstruct keys for completed sessions when old ephemeral private keys and raw shared secrets are gone and neither endpoint was compromised while they were in memory. An identity key compromised in the present enables future impersonation. This implemented property is supported by engineering validation, not formal cryptographic verification.
Transport boundary: UDPSEC authenticates and encrypts data and control packets within its scope, but does not prove AIS truthfulness or detect spoofing, guarantee UDP delivery or ordering, protect compromised endpoints, or provide complete denial-of-service resistance. It does not hide peer IP addresses, packet timing or lengths, or the cleartext ClientHello station identifier; NOSESSION hints are unauthenticated.
Read the security policy, behavioural contract, nmea_sproxy guide, and Wiki for the detailed boundaries.
nmea_sproxy and physical AIS receivers
Connect networked or physical AIS receivers through nmea_sproxy
nmea_sproxy is the station-side proxy that connects one local AIS source to one configured AISMixer destination.
Physical AIS receiver
serial port or USB virtual COM
nmea_sproxy
UDPSEC or explicitly trusted plain UDP
AISMixer
Implemented local inputs
- UDP from a local networked receiver or AIS application.
- Direct physical serial-port input.
- USB virtual COM input from a physical AIS receiver.
Implemented outputs
- Authenticated encrypted UDPSEC using the bounded session lifecycle described above.
- Explicit plain UDP for a trusted LAN, VPN, or equivalent boundary.
Clear relation boundary
One local input maps to one configured output. nmea_sproxy does not mix, fan out, route, deduplicate, assemble multipart AIS, or rewrite TAG metadata.
A networked receiver can feed local UDP into nmea_sproxy or send UDP directly to AISMixer, depending on the deployment. The main AISMixer process does not read serial ports directly. Trusted plain UDP does not provide UDPSEC encryption, authentication, replay protection, or liveness.
Deployment and operations
A Linux and systemd lifecycle built for real installations
The repository-managed deployment keeps runtime files, operator state, systemd integration, and local routing control aligned.
Repository-managed systemd
The service provisions /run/aismixer while AISMixer is running and supports the optional local control socket.
Install, update, and uninstall
Privilege-aware lifecycle scripts handle root or sudo operation and maintain the deployed runtime and service units.
Operator state preserved
Normal install, update, and uninstall flows preserve operator configuration and cryptographic keys.
Global routing CLI
The installed workflow places aismixerctl in /usr/local/bin for local routing operations.
Documentation and project status
Implemented foundations, clearly separated from what comes next
The Wiki is the detailed guide to architecture, configuration, routing, security, and operations. The Roadmap tracks future work without promising dates.
Implemented now
- Immutable IngressFrame production boundary with one retained legacy IngressEvent adapter.
- Bytes-native scanning, immutable half-open spans, parse-once fragment/TAG metadata, and the parsed assembler production path.
- The synchronous DataPlaneProcessor contract and PythonDataPlaneProcessor as the sole production and reference implementation.
- Explicit ingress fan-in, processor, and ordered egress stages with a completion barrier and process-local fail-fast task supervision.
- Logical routing, zones, and target-scoped deduplication.
- Runtime routing control with aismixerctl.
- Deterministic deduplication, assembly, and multipart TAG lifecycles.
- Hard-bounded handshake replay, pending-session, active-session, and private per-session nonce state.
- Immutable state statistics and a tested Python behavioural reference.
- Endpoint controls, physical receiver input through nmea_sproxy, and trusted plain-UDP proxy mode.
- systemd RuntimeDirectory, lifecycle scripts, and the global routing CLI.
Planned work
- A native implementation, bindings, and differential conformance execution; none exists today.
- Bytes-native assembler and output state beyond the current Python string compatibility boundary.
- Benchmarks and profiling before any performance claim.
- Coordinator and dedicated ingress/egress worker processes, multiprocessing, IPC, routing-snapshot distribution, and cross-process restart and recovery.
- A broader ingress and egress adapter architecture beyond the current UDP pathways.
Project community
Community and contact
Choose the public channel that fits the conversation. Discussions, Ideas, and Q&A help other users too; reproducible defects belong in Issues. Private contact remains available in the maintainer profile below.
Browse discussions
Explore public project conversations, announcements, deployment experience, field testing, and other community topics.
Browse GitHub DiscussionsShare an idea
Discussions is suitable for architecture proposals, integration ideas, deployment experience, AIS field testing, and academic or research collaboration that can be discussed publicly.
Open IdeasReport a problem
Use GitHub Issues for reproducible defects and concrete repository work, not general private correspondence.
Open GitHub IssuesAsk in Q&A
Use Q&A for focused questions about installation, configuration, usage, architecture, and operation.
Open Q&AFounder and maintainer
Iliyan Iliev, PhD
Founder, originator, and maintainer of AISMixer
Backend and network systems developer and researcher with interests in AIS/NMEA processing, maritime and regional security, transport, and tourism.
AI-assisted development: ChatGPT has supported architectural reasoning, planning, documentation, and review. OpenAI Codex has supported repository analysis, implementation, testing, and validation. Both tools are used under the founder’s direction; project decisions and final responsibility remain human.