How bertoldvdb/go-ais works
1. Repository purpose
- This is a Go library for AIS packet encoding and decoding.
- The architecture is intentionally split into two layers: a core AIS codec and an optional NMEA sentence wrapper for VDM/VDO input/output.
2. Core AIS subsystem (ais root package)
- The root package is the main data-processing engine.
- It works on AIS payloads as bit-oriented data, not on NMEA strings.
- Public entry points are centered around CodecNew, DecodePacket, and EncodePacket, which convert between raw AIS bits and strongly typed Go message structs.
3. Message model and generated codec tables
- messages.go defines the typed AIS message structures used by the decoder/encoder.
- codec.go plus codec_gen.go contain the codec logic and generated message-field handling.
- This suggests a code-generated mapping between AIS message IDs/fields and Go structs, which is important for both completeness and maintainability.
4. Build-time code generation
- parser_generator/main.go is the generator that produces codec_gen.go.
- Architecturally, this means the message schema is not hand-coded in full; the parser/generator pipeline is part of the repo’s build process and drives the core codec implementation.
5. NMEA convenience layer (aisnmea)
- The aisnmea package is a higher-level adapter for AIS messages carried inside NMEA sentences.
- It handles sentence parsing, multi-fragment assembly, and NMEA tag blocks, then hands the recovered AIS payload to the core codec.
- This keeps the AIS standard logic separate from transport/framing concerns, which is one of the repo’s explicit design goals.
6. NMEA framing and assembly
- aisnmea/nmea.go and aisnmea/assembler.go cover sentence parsing and fragment reassembly.
- aisnmea/tagblocks.go handles NMEA tag blocks, which are metadata prefixes often attached to VDM/VDO sentences.
- The flow here is: NMEA sentence(s) → assembled AIS payload → core decode.
7. Fast parsing path (aisnmeafast)
- aisnmeafast/parse.go is a separate optimized parser implementation.
- Its presence indicates a performance-oriented path for parsing NMEA-related input without changing the AIS codec itself.
- In the architecture diagram, this belongs on the NMEA side, alongside the convenience wrapper rather than inside the AIS codec core.
8. Decode and encode data flow
- Decode path: raw AIS bits or NMEA-framed AIS → parser/assembler → DecodePacket → typed AIS struct.
- Encode path: typed AIS struct → EncodePacket → AIS bit payload → NMEA encoder if the caller wants a sentence format.
- The repo treats AIS message semantics and NMEA transport as distinct stages, with a clean handoff between them.
9. Validation and regression coverage
- The repository includes extensive tests: decode_test.go, encode_fail_test.go, reencode_test.go, frequency_test.go, regression_test.go, and fuzz tests.
- testmsg/ and testdata/ provide real-world or corpus-based fixtures, including fuzz inputs and a sample NMEA file.
- This indicates the architecture is protected by corpus validation and round-trip checks, not just unit tests.
10. Practical boundary for diagramming
- If you are drawing the architecture, the key boundary is between:
- transport/framing: NMEA sentences, tag blocks, fragment assembly, fast parsing
- domain codec: AIS packet interpretation, typed messages, encode/decode generation
- The core library can operate without NMEA, while aisnmea is a convenience layer for AIS-in-NMEA integrations.
Main entry points: codec.go Codec API · nmea.go NMEA wrapper · tagblocks.go Tag blocks · parse.go Fast parse
Components 18
Core AIS codec
Bit-level AIS encoding and decoding, independent of NMEA framing.
- Codec API · Public entry points for creating codecs and decoding/encoding AIS packets.
codec.go - Messages · Typed AIS message definitions used by the codec.
messages.go - Codec tables · Generated field and message handling used by the core codec.
codec_gen.go
NMEA layer
Sentence parsing, assembly, and convenience wrappers around AIS payloads.
- NMEA wrapper · Higher-level entry point for AIS carried in NMEA sentences.
aisnmea/nmea.go - Assembler · Combines multi-fragment NMEA sentences into complete AIS payloads.
aisnmea/assembler.go - Tag blocks · Parses NMEA tag blocks attached to VDM/VDO sentences.
aisnmea/tagblocks.go - Fast parse · Performance-oriented NMEA parsing path.
aisnmeafast/parse.go
Code generation
Build-time generation that feeds the codec tables.
- Generator · Build-time generator that produces the codec table source.
parser_generator/main.go
Validation corpus
Tests and fixtures that protect decoding, encoding, and round-trip behavior.
- Decode tests · Core decode regression and correctness coverage.
decode_test.go - Encode tests · Checks encoding failures and invalid cases.
encode_fail_test.go - Reencode tests · Validates decode/encode symmetry over messages.
reencode_test.go - Regression tests · Protects against previously observed decoding issues.
regression_test.go - Fast parse tests · Covers the optimized NMEA parsing path.
fast_parse_test.go - NMEA tests · Tests for sentence parsing, assembly, and tag blocks.
aisnmea/nmea_test.go - Tag tests · Validates NMEA tag block parsing.
aisnmea/tagblocks_test.go - Fuzz corpus · Corpus used to harden AIS decoding against malformed inputs.
testdata/fuzz/FuzzDecode - Message corpus · Sample AIS message fixtures for round-trip and regression validation.
testmsg - NMEA sample · Sample NMEA sentence data used by the wrapper tests.
aisnmea/testdata/aistest.nmea
Connections 19
- Generator → Codec tables: generates · Produces the generated codec table source.
- Codec tables → Codec API: drives · Supplies message-field handling for encoding and decoding.
- Messages → Codec API: typed model · Defines the structured AIS messages handled by the codec.
- Codec API → Decode tests: verified by · Core decode behavior is exercised by tests.
- Codec API → Encode tests: verified by · Invalid encode paths are covered by tests.
- Codec API → Reencode tests: verified by · Round-trip behavior is validated against fixtures.
- Codec API → Regression tests: verified by · Regression coverage protects the core codec.
- Message corpus → Reencode tests: fixtures · Sample messages feed round-trip checks.
- Fuzz corpus → Decode tests: corpus · Fuzz corpus hardens decode behavior.
- NMEA wrapper → Assembler: uses · Wrapper relies on fragment assembly.
- NMEA wrapper → Tag blocks: uses · Wrapper parses NMEA metadata prefixes.
- Assembler → Codec API: hands off · Recovered AIS payload is decoded by the core codec.
- Tag blocks → NMEA wrapper: feeds · Tag block metadata is attached to parsed sentences.
- Fast parse → NMEA wrapper: accelerates · Optimized path for NMEA-oriented parsing.
- NMEA sample → NMEA tests: fixtures · Sample NMEA data supports wrapper tests.
- NMEA wrapper → NMEA tests: verified by · NMEA wrapper behavior is covered by tests.
- Tag blocks → Tag tests: verified by · Tag parsing is tested directly.
- Fast parse → Fast parse tests: verified by · Optimized parsing path is covered by tests.
- Codec API → NMEA wrapper: optional output · Core AIS payloads can be wrapped into NMEA sentences by higher-level callers.