pangbit/moonspoa/spop - mooncakes.io

pangbit/moonspoa/spop does not have a README file

SpopError

pub suberror SpopError {
  SpopError(code~ : StatusCode, message~ : String)
}

Protocol-level error of the SPOP protocol.

Carries a StatusCode that can be reported to the peer inside a DISCONNECT frame, plus a human-readable message.

impl Show for SpopError

SpopError::code

source

fn SpopError::code(self : SpopError) -> StatusCode

The status code carried by this error.

SpopError::message

source

fn SpopError::message(self : SpopError) -> String

The human-readable message carried by this error.

SpopError::new

source

fn SpopError::new(code : StatusCode, message : String) -> SpopError

Create a SpopError from a status code and a message.

Action

source

pub(all) enum Action {
  SetVar(VarScope, String, Data)
  UnsetVar(VarScope, String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

An action carried by an ACK frame, asking HAProxy to set or unset a variable. SetVar is action type 1 (3 arguments: scope, name, value), UnsetVar is action type 2 (2 arguments: scope, name).

Data

source

pub(all) enum Data {
  Null
  Bool(Bool)
  Int32(Int)
  UInt32(UInt)
  Int64(Int64)
  UInt64(UInt64)
  Ipv4(FixedArray[Byte])
  Ipv6(FixedArray[Byte])
  Str(String)
  Bin(Bytes)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A typed value carried by the SPOP protocol (TYPED-DATA).

On the wire the type id occupies the low 4 bits of the first byte and the flags the high 4 bits; for Bool the truth value is flag 0x10 (haproxy's SPOP_DATA_FL_TRUE).

Signed integers (Int32/Int64) are encoded by reinterpreting their two's complement bit pattern as an unsigned 64-bit integer which is then varint-encoded (a negative Int64 therefore occupies a 10-byte varint), matching haproxy's spoe_encode_data/spoe_decode_data. Decoding reads an unsigned 64-bit varint and reinterprets/truncates it.

Frame

source

pub(all) struct Frame {
  frame_type : FrameType
  fin : Bool
  abort : Bool
  stream_id : UInt64
  frame_id : UInt64
  payload : FramePayload
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A SPOP frame: <FRAME-TYPE><FLAGS><STREAM-ID><FRAME-ID><PAYLOAD>.

fin is flag bit 0 and must be set on every frame (fragmentation is not supported); abort is flag bit 1. stream_id and frame_id are varint-encoded on the wire.

Frame::ack

source

fn Frame::ack(stream_id : UInt64, frame_id : UInt64, actions : Array[Action]) -> Frame

Build an ACK frame carrying actions, echoing the stream and frame ids of the NOTIFY it answers.

Frame::disconnect

source

fn Frame::disconnect(frame_type : FrameType, status_code : StatusCode, message : String) -> Frame

Build a HAPROXY-DISCONNECT or AGENT-DISCONNECT frame reporting status_code and message.

Frame::hello

source

fn Frame::hello(frame_type : FrameType, args : Array[(String, Data)]) -> Frame

Build a HAPROXY-HELLO or AGENT-HELLO frame carrying args.

Frame::notify

source

fn Frame::notify(stream_id : UInt64, frame_id : UInt64, messages : Array[Message]) -> Frame

Build a NOTIFY frame carrying messages.

FramePayload

source

pub(all) enum FramePayload {
  KeyValues(Array[(String, Data)])
  Messages(Array[Message])
  Actions(Array[Action])
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

The payload of a SPOP frame, whose shape depends on the frame type: HELLO and DISCONNECT frames carry a key-value list, NOTIFY frames carry a list of messages, and ACK frames carry a list of actions.

FrameType

source

pub(all) enum FrameType {
  HAProxyHello
  HAProxyDisconnect
  Notify
  AgentHello
  AgentDisconnect
  Ack
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Type of a SPOP frame.

FrameType::from_int

source

fn FrameType::from_int(id : Int) -> FrameType?

Convert a wire frame type id to a FrameType; None for unknown ids.

FrameType::to_int

source

fn FrameType::to_int(self : FrameType) -> Int

The numeric frame type id on the wire.

HelloInfo

source

pub(all) struct HelloInfo {
  versions : Array[String]
  max_frame_size : UInt
  capabilities : Array[String]
  healthcheck : Bool
  engine_id : String?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

The parameters extracted from a HELLO frame (either direction).

Message

source

pub(all) struct Message {
  name : String
  args : Array[(String, Data)]
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A message carried by a NOTIFY frame: a name plus an ordered list of named arguments (the protocol encodes arguments in order).

StatusCode

source

pub(all) enum StatusCode {
  Normal
  IoError
  Timeout
  FrameTooBig
  InvalidFrame
  VersionNotFound
  MaxFrameSizeNotFound
  CapabilitiesNotFound
  UnsupportedVersion
  InvalidMaxFrameSize
  FragmentationNotSupported
  InvalidInterlacedFrames
  FrameIdNotFound
  ResourceAllocError
  UnknownError
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Status code reported in DISCONNECT frames and carried by SpopError.

StatusCode::from_uint

source

fn StatusCode::from_uint(code : UInt) -> StatusCode?

Convert a wire status code to a StatusCode; None for unknown codes.

StatusCode::to_uint

source

fn StatusCode::to_uint(self : StatusCode) -> UInt

The numeric status code on the wire.

VarScope

source

pub(all) enum VarScope {
  Process
  Session
  Transaction
  Request
  Response
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Scope of a variable set or unset by an Action.

VarScope::from_int

source

fn VarScope::from_int(id : Int) -> VarScope?

Convert a wire scope id to a VarScope; None for unknown ids.

VarScope::to_int

source

fn VarScope::to_int(self : VarScope) -> Int

The numeric id of a variable scope on the wire.

choose_version

source

fn choose_version(announced : Array[String]) -> String raise SpopError

Choose the protocol version to use given the versions announced by the peer in its "supported-versions" HELLO key. Versions have the form "Major.Minor"; announcing a major version implies support for all its minor versions. This library supports version "2.0", so any announced version with major version 2 matches. Raises StatusCode::UnsupportedVersion when there is no common version.

decode_data

source

fn decode_data(bytes : BytesView) -> Data? raise SpopError

Decode a TYPED-DATA value from the start of bytes. Returns None if more bytes are needed; raises SpopError on malformed input.

decode_frame

source

fn decode_frame(bytes : BytesView, max_frame_size? : UInt) -> Frame? raise SpopError

Decode a complete frame (length prefix included) from the start of bytes.

Returns None if bytes does not yet hold the whole frame (the caller should read more bytes and retry). Raises SpopError with StatusCode::FrameTooBig if the announced frame length exceeds max_frame_size, and with the appropriate status code on malformed input.

decode_frame_body

source

fn decode_frame_body(body : BytesView) -> Frame raise SpopError

Decode one frame body (everything after the 4-byte length prefix). body must contain exactly one frame body; truncated or trailing bytes raise SpopError with StatusCode::InvalidFrame.

decode_frame_length

source

fn decode_frame_length(bytes : BytesView) -> UInt?

Decode the 4-byte big-endian FRAME-LENGTH prefix. Returns None if fewer than 4 bytes are available.

decode_varint

source

fn decode_varint(bytes : BytesView) -> (UInt64, Int)? raise SpopError

Decode a SPOP varint from the start of bytes.

Returns the decoded value and the number of bytes consumed, or None if bytes does not yet contain a complete varint (the caller should read more data and retry). Raises SpopError with StatusCode::InvalidFrame if the varint is too long to fit in 64 bits or the accumulated value would overflow past bit 63.

default_max_frame_size

source

let default_max_frame_size : UInt

Default max-frame-size of the SPOP protocol (16380 bytes).

disconnect_args

source

fn disconnect_args(status_code : StatusCode, message : String) -> Array[(String, Data)]

The key-value list carried by a DISCONNECT frame for status_code and message: status-code (UINT32) and message (STRING).

encode_data

source

fn encode_data(data : Data) -> Bytes raise SpopError

Encode a TYPED-DATA value (type byte followed by the value).

encode_frame

source

fn encode_frame(frame : Frame) -> Bytes raise SpopError

Encode a complete frame, including the 4-byte big-endian length prefix.

encode_varint

source

fn encode_varint(i : UInt64) -> Bytes

Encode i as a SPOP varint.

hello_args

source

fn hello_args(versions? : Array[String], max_frame_size? : UInt, capabilities? : Array[String], healthcheck? : Bool, engine_id? : String?) -> Array[(String, Data)]

Build the key-value list of a HELLO frame announcing versions, max_frame_size and capabilities, plus optional healthcheck and engine_id.

min_frame_size

source

let min_frame_size : UInt

Minimum acceptable max-frame-size (256 bytes, per the SPOE spec).

negotiate_max_frame_size

source

fn negotiate_max_frame_size(ours : UInt, theirs : UInt) -> UInt raise SpopError

Compute the effective max-frame-size from our own and the peer's announced value: the minimum of both. Raises StatusCode::InvalidMaxFrameSize if the result is smaller than 256.

parse_disconnect_args

source

fn parse_disconnect_args(args : Array[(String, Data)]) -> (StatusCode, String) raise SpopError

Extract the status code and message from the key-value list of a DISCONNECT frame. Missing keys default to StatusCode::UnknownError and an empty message; entries of the wrong type raise StatusCode::InvalidFrame.

parse_hello_args

source

fn parse_hello_args(args : Array[(String, Data)]) -> HelloInfo raise SpopError

Parse the key-value list of a HELLO frame. Missing required keys raise the corresponding status code (VersionNotFound, MaxFrameSizeNotFound, CapabilitiesNotFound); keys of the wrong type raise InvalidFrame. Unknown keys are ignored.

parse_list

source

fn parse_list(s : String) -> Array[String]

Parse a comma-separated list such as the values of the "supported-versions" and "capabilities" HELLO keys. ASCII whitespace around items is ignored and empty items are dropped.

supported_version

source

let supported_version : String

The SPOP protocol version implemented by this library.

Source Files

Site source Report issue Packages Build queue Skills Statistics

#SpopError

#SpopError::code

#SpopError::message

#SpopError::new

#Action

#Data

#Frame

#Frame::ack

#Frame::disconnect

#Frame::hello

#Frame::notify

#FramePayload

#FrameType

#FrameType::from_int

#FrameType::to_int

#HelloInfo

#Message

#StatusCode

#StatusCode::from_uint

#StatusCode::to_uint

#VarScope

#VarScope::from_int

#VarScope::to_int

#choose_version

#decode_data

#decode_frame

#decode_frame_body

#decode_frame_length

#decode_varint

#default_max_frame_size

#disconnect_args

#encode_data

#encode_frame

#encode_varint

#hello_args

#min_frame_size

#negotiate_max_frame_size

#parse_disconnect_args

#parse_hello_args

#parse_list

#supported_version

Source Files

SpopError

SpopError::code

SpopError::message

SpopError::new

Action

Data

Frame

Frame::ack

Frame::disconnect

Frame::hello

Frame::notify

FramePayload

FrameType

FrameType::from_int

FrameType::to_int

HelloInfo

Message

StatusCode

StatusCode::from_uint

StatusCode::to_uint

VarScope

VarScope::from_int

VarScope::to_int

choose_version

decode_data

decode_frame

decode_frame_body

decode_frame_length

decode_varint

default_max_frame_size

disconnect_args

encode_data

encode_frame

encode_varint

hello_args

min_frame_size

negotiate_max_frame_size

parse_disconnect_args

parse_hello_args

parse_list

supported_version