🥮 mooncakes.io

moon-proxyproto

Strict HAProxy PROXY protocol v1/v2 codec, streaming decoder, TLV parser, and CRC32C validator for MoonBit.

moon add P7001/moon-proxyproto@0.1.0
Download zip
Author
Version
0.1.0
License
Apache-2.0
Repository
Last updated
12 days ago
Downloads
2
README

#moon-proxyproto

CI

moon-proxyproto is a strict MoonBit codec for HAProxy PROXY Protocol v1 and v2. It is not an HTTP proxy, reverse proxy, VPN, or connection forwarder.

The library decodes one PROXY header and returns the untouched application payload. It supports v1 TCP4/TCP6/UNKNOWN, v2 LOCAL/PROXY, IPv4, IPv6, UNIX address fields, STREAM and DGRAM transports, TLV boundary parsing, SSL TLV parsing, and Castagnoli CRC32C validation.

Wire validation is deliberately strict: the v1 limit is 107 bytes including CRLF, PROXY v2 accepts only registered family/transport combinations, and LOCAL v2 consumes its declared body while ignoring and normalizing its address metadata.

#Security

Only enable PROXY parsing on a connection accepted from a trusted proxy. A source address carried in a PROXY header is metadata, not an authenticated identity. The decoder never silently treats a malformed PROXY header as HTTP, TLS, SMTP, or another protocol. Configure an explicit policy at the trust boundary.

#Examples

let policy = DecodePolicy::v2_only()
match decode_v2(input, policy) {
  Ok(frame) => println("payload bytes: \{frame.remaining.length()}")
  Err(error) => println(error.context)
}

For streams, use Decoder::new(policy) and call feed with each received chunk. For UDP, call decode_datagram; it never joins two datagrams.

Executable examples are available under examples/decode_v1, decode_v2, preserve_payload, stream_chunks, tlv_inspect, http_preamble, and tls_preamble. Run one with, for example, moon run examples/decode_v1.

#Command-line inspection

proxyproto-tool provides decode-v1, decode-v2, decode-auto, encode-v1, encode-v2, inspect-tlv, verify-crc32c, split-test, and vector-check. Output is stable JSON. decode-auto is only an offline diagnostic command and must not be used as automatic protocol detection on a public listener.

#Validation

The local suite contains 156 named tests, 3888 chunk-split and truncation cases, 1000 deterministic v2 roundtrips, and 71 generated vectors. Vector metadata is checked against actual MoonBit parser results, including precise failure kinds and payload boundaries. See docs/test-matrix.md, docs/protocol-matrix.md, and docs/security.md for the tested matrix and trust boundary.

#Project status

This repository contains the active development version of moon-proxyproto.

  • GitHub repository: P7001/moon-proxyproto
  • Module namespace: P7001/moon-proxyproto
  • Current status: pre-release
  • Current version: 0.1.0-dev

#
AddressBlock

source
pub(all) enum AddressBlock {
  NoAddress
  Ipv4(Ipv4Endpoints)
  Ipv6(Ipv6Endpoints)
  UnixAddress(UnixEndpoints)
  RawUnsupported(Bytes)
} derive(
Debug)

#
AddressFamily

source
pub(all) enum AddressFamily {
  Unspec
  Inet
  Inet6
  Unix
} derive(Eq, 
Debug)

#
ByteCursor

source
pub struct ByteCursor {
  input : Bytes
  position_value : Int
} derive(
Debug)

#
ByteCursor::checkpoint

source
fn ByteCursor::checkpoint(self : ByteCursor) -> Int

#
ByteCursor::new

source
fn ByteCursor::new(input : Bytes) -> ByteCursor

#
ByteCursor::peek

source
fn ByteCursor::peek(self : ByteCursor) -> Byte?

#
ByteCursor::peek_n

source
fn ByteCursor::peek_n(self : ByteCursor, count : Int) -> Bytes?

#
ByteCursor::position

source
fn ByteCursor::position(self : ByteCursor) -> Int

#
ByteCursor::read_exact

source
fn ByteCursor::read_exact(self : ByteCursor, count : Int) -> Bytes?

#
ByteCursor::read_u16_be

source
fn ByteCursor::read_u16_be(self : ByteCursor) -> Int?

#
ByteCursor::read_u32_be

source
fn ByteCursor::read_u32_be(self : ByteCursor) -> UInt?

#
ByteCursor::read_u8

source
fn ByteCursor::read_u8(self : ByteCursor) -> Byte?

#
ByteCursor::remaining

source
fn ByteCursor::remaining(self : ByteCursor) -> Int

#
ByteCursor::restore

source
fn ByteCursor::restore(self : ByteCursor, checkpoint : Int) -> Unit

#
ByteCursor::skip

source
fn ByteCursor::skip(self : ByteCursor, count : Int) -> Bool

#
ChunkBuffer

source
pub struct ChunkBuffer {
  chunks : Array[Bytes]
  first_chunk : Int
  first_offset : Int
  available_bytes : Int
  copied_bytes_value : Int
} derive(
Debug)

A queue of immutable input chunks. Bytes are copied only by copy_exact.

#
ChunkBuffer::append

source
fn ChunkBuffer::append(self : ChunkBuffer, chunk : Bytes) -> Unit

#
ChunkBuffer::available

source
fn ChunkBuffer::available(self : ChunkBuffer) -> Int

#
ChunkBuffer::chunk_count

source
fn ChunkBuffer::chunk_count(self : ChunkBuffer) -> Int

#
ChunkBuffer::clear

source
fn ChunkBuffer::clear(self : ChunkBuffer) -> Unit

#
ChunkBuffer::copied_bytes

source
fn ChunkBuffer::copied_bytes(self : ChunkBuffer) -> Int

#
ChunkBuffer::copy_exact

source
fn ChunkBuffer::copy_exact(self : ChunkBuffer, length : Int) -> Bytes?

#
ChunkBuffer::discard

source
fn ChunkBuffer::discard(self : ChunkBuffer, length : Int) -> Bool

#
ChunkBuffer::new

source

#
ChunkBuffer::peek_byte

source
fn ChunkBuffer::peek_byte(self : ChunkBuffer, offset : Int) -> Byte?

#
Command

source
pub(all) enum Command {
  Local
  Proxy
} derive(Eq, 
Debug)

#
DecodePolicy

source
pub(all) struct DecodePolicy {
  expected_protocol : ExpectedProtocol
  max_v1_line_bytes : Int
  max_v2_payload_bytes : Int
  verify_crc32c : Bool
  require_crc32c : Bool
  allow_local_command : Bool
  allow_unspec : Bool
  preserve_unknown_tlvs : Bool
} derive(
Debug)

#
DecodePolicy::strict

source
fn DecodePolicy::strict() -> DecodePolicy

#
DecodePolicy::v1_only

source
fn DecodePolicy::v1_only() -> DecodePolicy

#
DecodePolicy::v2_only

source
fn DecodePolicy::v2_only() -> DecodePolicy

#
DecodeProgress

source
pub(all) enum DecodeProgress {
  NeedMore
  Done(DecodedFrame)
  Failed(ProxyError)
} derive(
Debug)

#
DecodedFrame

source
pub(all) struct DecodedFrame {
  header : ProxyHeader
  remaining : Bytes
  consumed : Int
} derive(
Debug)

#
Decoder

source
pub struct Decoder {
  policy : DecodePolicy
  buffer : ChunkBuffer
  state_value : DecoderState
  failure : ProxyError?
} derive(
Debug)

#
Decoder::buffered_len

source
fn Decoder::buffered_len(self : Decoder) -> Int

#
Decoder::feed

source
fn Decoder::feed(self : Decoder, chunk : Bytes) -> DecodeProgress

#
Decoder::new

source
fn Decoder::new(policy : DecodePolicy) -> Decoder

#
Decoder::reset

source
fn Decoder::reset(self : Decoder) -> Unit

#
Decoder::state

source
fn Decoder::state(self : Decoder) -> DecoderState

#
DecoderState

source
pub(all) enum DecoderState {
  AwaitingPrefix
  ReadingV1Line
  ReadingV2Fixed
  ReadingV2Body(Int)
  Done
  Failed
} derive(Eq, 
Debug)

#
ExpectedProtocol

source
pub(all) enum ExpectedProtocol {
  V1Only
  V2Only
  V1OrV2
} derive(Eq, 
Debug)

#
GeneratedVector

source
pub(all) struct GeneratedVector {
  name : String
  parser : String
  data : Bytes
  expected_success : Bool
  expected_error : String
  expected_consumed : Int
  expected_remaining_length : Int
  expected_family : String
  expected_transport : String
}

#
Ipv4Address

source
pub(all) struct Ipv4Address {
  octets : FixedArray[Byte]
} derive(
Debug)

#
Ipv4Address::new

source
fn Ipv4Address::new(octets : FixedArray[Byte]) -> Result[Ipv4Address, ProxyError]

#
Ipv4Endpoints

source
pub(all) struct Ipv4Endpoints {
  source_address : Ipv4Address
  destination_address : Ipv4Address
  source_port : Int
  destination_port : Int
} derive(
Debug)

#
Ipv6Address

source
pub(all) struct Ipv6Address {
  octets : FixedArray[Byte]
} derive(
Debug)

#
Ipv6Address::new

source
fn Ipv6Address::new(octets : FixedArray[Byte]) -> Result[Ipv6Address, ProxyError]

#
Ipv6Endpoints

source
pub(all) struct Ipv6Endpoints {
  source_address : Ipv6Address
  destination_address : Ipv6Address
  source_port : Int
  destination_port : Int
} derive(
Debug)

#
ParsedTlv

source
pub(all) enum ParsedTlv {
  Alpn(Bytes)
  Authority(String)
  Crc32c(UInt)
  Noop(Bytes)
  UniqueId(Bytes)
  Ssl(SslInfo)
  Netns(String)
  Custom(Byte, Bytes)
  Experimental(Byte, Bytes)
  FutureReserved(Byte, Bytes)
  Unknown(Byte, Bytes)
} derive(
Debug)

#
PropertyGenerator

source
pub struct PropertyGenerator {
  state : UInt
} derive(
Debug)

Deterministic xorshift32 generator for reproducible protocol tests.

#
PropertyGenerator::new

source
fn PropertyGenerator::new(seed : UInt) -> PropertyGenerator

#
PropertyGenerator::next_byte

source
fn PropertyGenerator::next_byte(self : PropertyGenerator) -> Byte

#
PropertyGenerator::next_bytes

source
fn PropertyGenerator::next_bytes(self : PropertyGenerator, length : Int) -> Bytes

#
PropertyGenerator::next_ipv4

source

#
PropertyGenerator::next_ipv6

source

#
PropertyGenerator::next_payload

source
fn PropertyGenerator::next_payload(self : PropertyGenerator) -> Bytes

#
PropertyGenerator::next_port

source
fn PropertyGenerator::next_port(self : PropertyGenerator) -> Int

#
PropertyGenerator::next_u32

source
fn PropertyGenerator::next_u32(self : PropertyGenerator) -> UInt

#
PropertyGenerator::next_unknown_tlv

source
fn PropertyGenerator::next_unknown_tlv(self : PropertyGenerator) -> RawTlv

#
PropertyGenerator::next_v2_header

source
fn PropertyGenerator::next_v2_header(self : PropertyGenerator) -> ProxyHeader

#
ProxyError

source
pub(all) struct ProxyError {
  kind : ProxyErrorKind
  offset : Int
  context : String
} derive(
Debug)

#
ProxyErrorKind

source
pub(all) enum ProxyErrorKind {
  NeedMoreData
  InvalidPrefix
  UnsupportedVersion
  InvalidCommand
  InvalidFamily
  InvalidTransport
  InvalidFamilyTransport
  InvalidV1Line
  V1LineTooLong
  MissingCrlf
  InvalidIpv4
  InvalidIpv6
  InvalidPort
  InvalidV2Signature
  InvalidLength
  HeaderTooLarge
  TruncatedAddress
  TruncatedTlv
  InvalidTlv
  DuplicateCrc32c
  MissingCrc32c
  Crc32cMismatch
  InvalidSslTlv
  PolicyViolation
  DecoderAlreadyFinished
  DecoderFailed
} derive(Eq, 
Debug)

#
ProxyHeader

source
pub(all) struct ProxyHeader {
  version : ProxyVersion
  command : Command
  family : AddressFamily
  transport : Transport
  address : AddressBlock
  tlvs : Array[RawTlv]
} derive(
Debug)

#
ProxyHeader::new

source
fn ProxyHeader::new(version : ProxyVersion, command : Command, family : AddressFamily, transport : Transport, address : AddressBlock, tlvs : Array[RawTlv]) -> Result[ProxyHeader, ProxyError]

#
ProxyVersion

source
pub(all) enum ProxyVersion {
  V1
  V2
} derive(Eq, 
Debug)

#
RawTlv

source
pub(all) struct RawTlv {
  type_code : Byte
  value : Bytes
} derive(
Debug)

#
SslInfo

source
pub(all) struct SslInfo {
  client_flags : Byte
  verify : UInt
  sub_tlvs : Array[RawTlv]
} derive(
Debug)

#
SslTlv

source
pub(all) struct SslTlv {
  client_flags : Byte
  verify : UInt
  sub_tlvs : Array[RawTlv]
} derive(
Debug)

#
TlvRange

source
pub(all) enum TlvRange {
  Registered
  CustomRange
  ExperimentalRange
  FutureReservedRange
  UnknownRange
} derive(Eq, 
Debug)

#
Transport

source
pub(all) enum Transport {
  Unspec
  Stream
  Datagram
} derive(Eq, 
Debug)

#
UnixEndpoints

source
pub(all) struct UnixEndpoints {
  source : Bytes
  destination : Bytes
} derive(
Debug)

#
VectorMetadata

source
pub(all) struct VectorMetadata {
  name : String
  category : String
  expected_success : Bool
  expected_error : String
  expected_consumed : Int
  expected_remaining_length : Int
  expected_family : String
  expected_transport : String
} derive(
Debug)

#
GENERATED_VECTOR_COUNT

source
let GENERATED_VECTOR_COUNT : Int

#
TLV_ALPN

source
let TLV_ALPN : Byte

#
TLV_AUTHORITY

source
let TLV_AUTHORITY : Byte

#
TLV_CRC32C

source
let TLV_CRC32C : Byte

#
TLV_NETNS

source
let TLV_NETNS : Byte

#
TLV_NOOP

source
let TLV_NOOP : Byte

#
TLV_SSL

source
let TLV_SSL : Byte

#
TLV_SSL_CIPHER

source
let TLV_SSL_CIPHER : Byte

#
TLV_SSL_CLIENT_CERT

source
let TLV_SSL_CLIENT_CERT : Byte

#
TLV_SSL_CN

source
let TLV_SSL_CN : Byte

#
TLV_SSL_GROUP

source
let TLV_SSL_GROUP : Byte

#
TLV_SSL_KEY_ALG

source
let TLV_SSL_KEY_ALG : Byte

#
TLV_SSL_SIG_ALG

source
let TLV_SSL_SIG_ALG : Byte

#
TLV_SSL_SIG_SCHEME

source
let TLV_SSL_SIG_SCHEME : Byte

#
TLV_SSL_VERSION

source
let TLV_SSL_VERSION : Byte

#
TLV_UNIQUE_ID

source
let TLV_UNIQUE_ID : Byte

#
assert_all_prefix_truncations

source
fn assert_all_prefix_truncations(header : Bytes, policy : DecodePolicy) -> Int

#
assert_all_single_splits

source
fn assert_all_single_splits(input : Bytes, policy : DecodePolicy) -> Int

#
assert_bytes_eq

source
fn assert_bytes_eq(actual : Bytes, expected : Bytes) -> Unit

#
assert_err_kind

source
fn assert_err_kind(result : Result[DecodedFrame, ProxyError], expected : ProxyErrorKind) -> Unit

#
assert_header_eq

source
fn assert_header_eq(actual : ProxyHeader, expected : ProxyHeader) -> Unit

#
assert_ok

source
fn assert_ok(result : Result[DecodedFrame, ProxyError]) -> DecodedFrame

#
assert_remaining_eq

source
fn assert_remaining_eq(frame : DecodedFrame, expected : Bytes) -> Unit

#
assert_roundtrip_v1

source
fn assert_roundtrip_v1(header : ProxyHeader) -> Unit

#
assert_roundtrip_v2

source
fn assert_roundtrip_v2(header : ProxyHeader) -> Unit

#
assert_selected_three_way_splits

source
fn assert_selected_three_way_splits(input : Bytes, cuts : Array[Int], policy : DecodePolicy) -> Int

#
bytes_concat

source
fn bytes_concat(left : Bytes, right : Bytes) -> Bytes

#
bytes_equal_constant_time

source
fn bytes_equal_constant_time(left : Bytes, right : Bytes) -> Bool

#
bytes_slice

source
fn bytes_slice(input : Bytes, start : Int, end : Int) -> Result[Bytes, ProxyError]

#
classify_tlv_range

source
fn classify_tlv_range(type_code : Byte) -> TlvRange

#
count_single_split_cases

source
fn count_single_split_cases(input : Bytes) -> Int

#
count_three_way_cases

source
fn count_three_way_cases(first_cuts : Array[Int], second_cuts : Array[Int]) -> Int

#
crc32c

source
fn crc32c(data : Bytes) -> UInt

#
crc32c_reference

source
fn crc32c_reference(data : Bytes) -> UInt

#
decode_datagram

source
fn decode_datagram(datagram : Bytes, policy : DecodePolicy) -> Result[DecodedFrame, ProxyError]

#
decode_v1

source
fn decode_v1(input : Bytes, policy : DecodePolicy) -> Result[DecodedFrame, ProxyError]

#
decode_v2

source
fn decode_v2(input : Bytes, policy : DecodePolicy) -> Result[DecodedFrame, ProxyError]

#
encode

source
fn encode(header : ProxyHeader) -> Result[Bytes, ProxyError]

#
encode_ssl_tlv

source
fn encode_ssl_tlv(ssl : SslTlv) -> Result[RawTlv, ProxyError]

#
encode_tlvs

source
fn encode_tlvs(tlvs : Array[RawTlv]) -> Result[Bytes, ProxyError]

#
encode_v1

source
fn encode_v1(header : ProxyHeader) -> Result[Bytes, ProxyError]

#
encode_v2

source
fn encode_v2(header : ProxyHeader) -> Result[Bytes, ProxyError]

#
encode_with_payload

source
fn encode_with_payload(header : ProxyHeader, payload : Bytes) -> Result[Bytes, ProxyError]

#
feed_single_split

source
fn feed_single_split(input : Bytes, split : Int, policy : DecodePolicy) -> DecodeProgress

#
feed_three_way

source
fn feed_three_way(input : Bytes, first_cut : Int, second_cut : Int, policy : DecodePolicy) -> DecodeProgress

#
find_all_tlvs

source
fn find_all_tlvs(tlvs : Array[RawTlv], type_code : Byte) -> Array[RawTlv]

#
find_tlv

source
fn find_tlv(tlvs : Array[RawTlv], type_code : Byte) -> RawTlv?

#
format_ipv4

source
fn format_ipv4(address : Ipv4Address) -> String

#
format_ipv6

source
fn format_ipv6(address : Ipv6Address) -> String

#
generated_vectors

source
fn generated_vectors() -> Array[GeneratedVector]

#
header_semantic_eq

source
fn header_semantic_eq(left : ProxyHeader, right : ProxyHeader) -> Bool

#
hex_decode

source
fn hex_decode(input : String) -> Result[Bytes, ProxyError]

#
hex_encode

source
fn hex_encode(input : Bytes) -> String

#
insert_proxy_crc32c

source
fn insert_proxy_crc32c(header_without_checksum : ProxyHeader) -> Result[Bytes, ProxyError]

#
interpret_all_tlvs

source
fn interpret_all_tlvs(tlvs : Array[RawTlv]) -> Result[Array[ParsedTlv], ProxyError]

#
interpret_tlv

source
fn interpret_tlv(tlv : RawTlv, offset? : Int) -> Result[ParsedTlv, ProxyError]

#
parse_ipv4_text

source
fn parse_ipv4_text(input : String) -> Result[Ipv4Address, ProxyError]

#
parse_ipv6_text

source
fn parse_ipv6_text(input : String) -> Result[Ipv6Address, ProxyError]

#
parse_port_text

source
fn parse_port_text(input : String) -> Result[Int, ProxyError]

#
parse_ssl_tlv

source
fn parse_ssl_tlv(value : Bytes, offset? : Int) -> Result[SslTlv, ProxyError]

#
parse_tlvs

source
fn parse_tlvs(input : Bytes, offset? : Int, preserve_unknown? : Bool) -> Result[Array[RawTlv], ProxyError]

#
proxy_error

source
fn proxy_error(kind : ProxyErrorKind, offset : Int, context : String) -> ProxyError

#
read_u16_be

source
fn read_u16_be(input : Bytes, offset : Int) -> Result[Int, ProxyError]

#
read_u32_be

source
fn read_u32_be(input : Bytes, offset : Int) -> Result[UInt, ProxyError]

#
tlv_type_name

source
fn tlv_type_name(type_code : Byte) -> String

#
unix_address_field

source
fn unix_address_field(input : Bytes) -> Result[Bytes, ProxyError]

#
unix_address_text_view

source
fn unix_address_text_view(raw : Bytes) -> String?

#
v2_signature

source
fn v2_signature() -> Bytes

#
vector_metadata

source
fn vector_metadata(name : String, category : String, expected_success : Bool, expected_error : String, expected_consumed : Int, expected_remaining_length : Int, expected_family : String, expected_transport : String) -> VectorMetadata

#
verify_generated_vectors

source
fn verify_generated_vectors() -> Result[Int, ProxyError]

#
verify_proxy_crc32c

source
fn verify_proxy_crc32c(complete_header : Bytes) -> Result[Unit, ProxyError]

#
write_u16_be

source
fn write_u16_be(value : Int) -> Bytes

#
write_u32_be

source
fn write_u32_be(value : UInt) -> Bytes

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io