ISO8583 codec gear
The signal leveler for financial protocol normalization.
The codec_iso8583 gear functions as the Signal Leveler (Normalization Engine) of the payment mixer. It is a Native Gear (Go) responsible for transforming raw, "noisy" protocol dialects (ISO8583 binary/BCD) into a clean, structured fluxMsg (CBOR) format.
The gear uses the Moov ISO8583 engine. The engine levels technical variances between card schemes into a uniform semantic layer for the internal Master Bus Architecture.
| Attribute | Details |
|---|---|
| Analogy | Signal Leveler (Normalization) |
| Source Code | pkg/gears/native/iso8583/codec |
| Pairs With | Signal Pre-amp (Capture) |
| Always Emitted Metadata | codec.protocol, codec.spec_hash, codec.spec_id, codec.spec_version, iso8583.mti, [alias] |
| Conditionally Emitted Metadata | iso8583.mti_class (when the MTI is at least two digits), codec.violations (when validation is on and a rule was broken) |
| Mandatory Consumed Metadata | [alias] or iso8583.field.N |
| Signals Sent | conn.close (Kill Switch) |
Reference
fluxrig gears doc codec_iso8583 generates the identity, ports, and configuration below from the gear's manifest, so they stay in lockstep with the code.
| Type | codec_iso8583 |
| Category | codec |
| Status | stable |
| Terminus | transparent |
ISO 8583 encode/decode against an SDL spec: raw wire bytes <-> structured fluxMsg fields.
Ports
| Port | Direction | Role | Summary |
|---|---|---|---|
in | input | message | Message to encode or decode. |
out | output | message | Encoded or decoded message. A decode also sets iso8583.mti and iso8583.mti_class, the latter being the leading digits a request and its reply share. |
Configuration
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
direction | enum: auto, encode, decode | auto | encode, decode, or auto (infer from the message). | |
on_error | enum: reject, drop, kill | drop | on a decode/encode failure, or on a message a rule rejects: reject (emit on the error path), drop (discard), or kill (fail the gear). | |
spec | string | - | Legacy alias of spec_path. | |
spec_path | string | - | The ISO 8583 SDL spec: a path to a file, or a store reference as name:tag (e.g. acme-auth:v2.2.0) or a content hash. | |
validation | enum: off, warn, enforce | off | what the spec's semantic rules do to traffic: off (they document), warn (violations are recorded and the message goes on), or enforce (a rejecting rule fails the message, which then follows on_error). |
Architectural signal path
The Codec Gear operates at the heart of the "Channel Strip," performing protocol translation between raw financial signals and the internal bus models.
NOTE
Every arrow above is a unidirectional wire. The request/response duality of the external socket never reaches the codec. The diagram shows both translation directions in one box for compactness. In a real scenario each codec instance uses a single direction (decode or encode). A request/response path typically uses two codec instances: one decoding what the I/O gear received, and one encoding what will be written back. See the I/O gear signal path for how one bidirectional socket maps onto two unidirectional ports.
Technical description
Unlike the IO TCP Gear, which handles transport framing, the Signal Leveler focuses purely on Semantic Protocol logic. It parses fields. It checks data types. It adheres to scheme-specific dialects.
Core engine: Moov ISO8583
The gear uses a YAML SDL to define dialect rules, powered by Moov ISO8583:
- Industry Standard Parsing: Support for BCD, EBCDIC, ASCII, and raw Binary payloads.
- Deep Bitmaps: Automatic handling of Primary and Secondary bitmaps (Support for up to 128 fields). Tertiary Bitmaps (Field 129-192) are currently a roadmap item (future).
- EMV & Composites: Normalization for BER-TLV (Field 55) and complex subfields (Field 48, 62, 127).
Configuration reference
The Manifest reference table at the top of this page carries the full field list, with types and defaults. This gear follows the Stack is the Spec principle. We do not reinvent the protocol parser. We embed the standard Moov library.
Specification resolution
A spec reaches the gear from a file or from the content-addressable store.
spec_path names either a file or a stored artefact. You tell the two apart
by shape. A path has a directory separator or a .yaml/.yml extension and
no colon. A store reference is name:tag (payment-v1:stable) or a bare
content hash.
Both exist for a reason. A spec under development is a file, and iterating on it should not require an import. A spec in a deployment is an artefact: the Mixer resolves the references a scenario names against its own store and sends them with the scenario, and the Rack files them before applying it. Two Racks given one scenario therefore compile the same bytes, which a path cannot promise. It resolves against whatever each Rack happens to have at that location.
A spec that arrived from the store has no directory of its own, so its
wire.source cannot name a relative file. Name a base with moov: or carry the
wire layer in wire.fields.
Import. fluxrig spec import <file> files a spec under the name and version
it declares (spec.name and spec.version), the same values that appear in the
document. Importing identical content again is idempotent. The import refuses a document claiming a
version that already names different content. A version identifies one
set of bytes, or it identifies nothing.
NOTE
The SHA256 of its content (first 12 characters) tracks every spec.
The Codec gear stamps codec.spec_hash on each message it processes, in both
directions. A transaction traces to the exact bytes that parsed it.
That is a stronger statement than the version the store filed it under.
Operational guardrails
Stateless Mastery
The codec_iso8583 is a stateless processor. Metadata mappings (aliases) enable the Asymmetric Bus (Coat Check) pattern, allowing the system to scale without sticky sessions.
Network Management (MTI 0800) While the gear parses 0800 messages, the downstream Logic Gears (within a scenario) generate the appropriate responses.
Resilience & error handling
- Parsing Failures: If raw bytes cannot be unpacked (invalid bitmap/length), the gear raises a
codecerror. - Validation Failures: If fields defined in YAML are missing or invalid, the gear raises a
validationerror. - Field Constraints: Support is currently optimized for ISO8583:1987/1993 dialects using Primary and Secondary bitmaps.
- The Kill Switch: If you set
on_error: "kill", the gear signals the Pre-amp via the Control Plane (flux.ctrl.{io_gear_id}) to terminate the connection.
Resource monitoring (OTel)
The codec_iso8583 gear exports metrics for dashboarding and alerting:
flux.gear.messages_in(Counter): Total messages processed by the gear.flux.gear.processing_time_ms(Histogram): Processing latency distribution in milliseconds.flux.codec.iso8583.fields_count(Histogram): Average field density per message.flux.gear.errors(Counter): Cumulative count of packing/unpacking failures.
TIP
See the Signal Leveler Implementation Guide for YAML dialect definitions in depth, and the protocol reference for the document fluxrig spec doc renders from one.