Rust implementation and BOAWP data validation tool https://boawp.org
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.
 
 
Alex Williams 1c25aef313
Update URLs
8 months ago
.github/workflows Run tests through Makefile 9 months ago
src Update URLs 8 months ago
testdata Update documentation comments and noop.bin test file. Build release by default 8 months ago
.gitignore Add initial validator code for HTTP 9 months ago
Cargo.lock Remove byteorder crate dependency. Move I/O outside of decoding 8 months ago
Cargo.toml Update URLs 8 months ago
LICENSE First commit 9 months ago
Makefile Update documentation comments and noop.bin test file. Build release by default 8 months ago
README.md Update URLs 8 months ago

README.md

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/lib.rs as well as a binary in src/bin/validate.rs.

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.

Usage

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.

Notes

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

Contributing

License

MIT License

Copyright (c) 2020 Alexander Williams, On-Prem license@on-premises.com