Rust implementation and BOAWP data validation tool
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

4.3 KiB

BOAWP validator

Binary Oriented Application Wire Protocol

The BOAWP validator is a decoder implementation, written in Rust, for the BOAWP specification (Binary Oriented Application Wire Protocol).

It is used to validate BOAWP frames and ensure implementations are compliant with the spec.

This repo contains a library in src/ as well as a binary in src/bin/

Getting started

A Rust environment (2018 edition) is required to compile the binary. It's fairly easy to install, just follow the instructions here:

This code was tested with Rust v1.47.0 on arm64.

Once the cargo and rustc commands are available, run the following commands:

  • cargo test: this ensures all the unit tests pass on your system.
  • cargo build: this builds the binary which will be used to test your data.
  • cargo doc: this builds the library documentation for more info on the internals.

Alternatively, just type make.

You should then have the binary in target/release/validate, as well as HTML docs in target/doc/boawp_validator.


In most cases, calling the binary directly against files generated by your implementation should be sufficient.

BOAWP binary usage

The binary only takes one argument: the filename to be decoded.

target/release/validate testdata/noop.bin
Decoded: (Init { name: 'B', version: '0', status: 'A', lf: '\n' }, Fixed { null: 0, cmd: '\n', hlength: 0, blength: 0, command: "NOOP" }, Headers { headers: [] }, Body { body: [] })

If decoding is successful, the exit code is 0 and the Decoded... result will appear in STDOUT.

If decoding fails, the exit code is -1 and the Error... result will appear in STDERR.

BOAWP library usage

Types that implements the Read trait can be passed to the validate() function. It can be a File, TcpStream, BufReader, etc.

use std::io::BufReader;
use boawp_validator::*;

// The data we want to decode, a simple NOOP frame
let data: [u8; 12] = [66, 48, 65, 10, 0, 10, 0, 0, 0, 0, 0, 0];

// Create a BufReader to buffer the data
let mut reader = BufReader::new(&data[..]);

// Validate the BOAWP frame
let validated = validate(&mut reader).unwrap();

assert_eq!(validated.0, Init { name: 'B', version: '0', status: 'A', lf: '\n' });
assert_eq!(validated.1, Fixed { null: 0, cmd: '\n', hlength: 0, blength: 0, command: "NOOP".to_string() });
assert_eq!(validated.2, Headers { headers: vec![] });
assert_eq!(validated.3, Body { body: vec![] });

The library should never panic, even when the data is not compliant with the BOAWP specification. It should always return either an Ok() or Err() result with a message.


This code is hardcoded to work with the HTTP protocol, so encoded headers will need to use the HTTP headers from the BOAWP registry.

Compliant implementations

Below is a list of compliant BOAWP implementations. Compliance means:

  • this validator successfully decodes all data emitted by the implementation's encoder.
  • the implementation successfully decodes the good-*.bin files in the testdata/ directory.
  • the implementation fails to decode the bad-*.bin files in the testdata/ directory.
  • the implementation successfully passes all the compliance tests in the BOAWP specification.
Name/Repo Language Decoder Encoder Description
boawp-validator Rust Yes Yes Reference implementation
picolisp-boawp PicoLisp Yes Yes Reference implementation
ruby-boawp Ruby Yes Yes Reference implementation



MIT License

Copyright (c) 2020 Alexander Williams, On-Prem