#pangbit/moonspoa

#Packages

#Requirements and validation status

• Development and local validation used macOS arm64, moon 0.1.20260920 and moonc v0.10.14+7d59c7ec9. These are tested versions, not an established minimum toolchain version.
• The module declares moonbitlang/async@0.22.1 and defaults to the native backend. Native builds require a C compiler and platform development headers.
• The server's C stub uses POSIX Unix socket APIs. Native does not imply support for every operating system: Linux has been validated on Ubuntu 24.04 (x86_64); the current server transport does not support Windows.
• Manual validation covers release-mode tests, generated documentation, testing the extracted package, and an independent consumer's UDS round trip. On Linux, the full test suite passes, and end-to-end interoperability with HAProxy 3.4.4 (built from source) has been verified over both TCP and UDS transports, including concurrent pipelined traffic, option spop-check health checks with fail-open, and agent restarts.
• GitHub Actions CI (ubuntu-24.04) is configured to check types, debug/release tests, formatting and generated interfaces. Its HAProxy 3.4 TCP smoke test checks denial, a 50-request concurrent burst, and forwarding after an agent restart. Documentation generation, extracted-package and independent-consumer checks, HAProxy-to-UDS interoperability, spop-check, and outage fail-open remain manual validation; they are not covered by this workflow. See CI runs for results tied to a specific commit.
• This is an initial 0.1.0 release candidate. The checks above are not a production-readiness certification.

#Installation

moon add pangbit/moonspoa

#Quick start

#Agent server

import {
  "pangbit/moonspoa/agent",
  "pangbit/moonspoa/server",
  "moonbitlang/async",
}
supported_targets = "native"
pkgtype(kind: "executable")

///|
async fn main {
  let agent = @agent.Agent::new().on("check-ip", fn(msg) {
    // This minimal example accepts the demo client's string value.
    // HAProxy's `args ip=src` sends Ipv4/Ipv6; see examples/server.
    guard msg.args is [("ip", Str(ip)), ..] else { return [] }
    // HAProxy adds the scope and configured variable prefix.
    [SetVar(Transaction, "ip_blocked", Bool(ip == "203.0.113.7"))]
  })
  let server = @server.Server::bind(
    agent,
    @server.Listener::tcp("127.0.0.1:12345"),
  )
  defer server.close()
  server.run()
}

#SPOE client

import {
  "pangbit/moonspoa/client",
  "moonbitlang/async",
  "moonbitlang/async/socket",
}
supported_targets = "native"
pkgtype(kind: "executable")

///|
async fn main {
  let conn = @socket.Tcp::connect(@socket.Addr::parse("127.0.0.1:12345"))
  defer conn.close()
  let client = @client.Client::hello(conn, conn)
  let actions = client.notify_messages([
    { name: "check-ip", args: [("ip", Str("203.0.113.7"))], },
  ])
  for action in actions {
    println("\{Repr(action)}")
  }
  ignore(client.disconnect())
}

#Concurrent requests and timeouts

///|
async fn query_all(client : @client.Client, ips : Array[String]) -> Unit {
  client.with_pipelining(fn(client) {
    @async.with_task_group(group => {
      for ip in ips {
        group.spawn_bg(() => {
          let actions = client.notify_messages(
            [{ name: "check-ip", args: [("ip", Str(ip))], }],
            timeout=1000,
          )
          println("\{Repr(actions)}")
        })
      }
    })
  })
}

#Protocol types through the root facade

///|
test {
  let message : @moonspoa.Message = {
    name: "check-ip",
    args: [("ip", Str("1.2.3.4"))],
  }
  let frame = @moonspoa.Frame::notify(0, 1, [message])
  debug_inspect(frame.frame_type, content="Notify")
}

#Runnable examples

# Terminal 1: agent server
moon run examples/server -- --port 12345 --block 203.0.113.7
# Terminal 2: send an IP and print the ACK actions and verdict
moon run examples/client -- --port 12345 203.0.113.7

#HAProxy integration

spoe-message check-ip
    args ip=src
    event on-frontend-http-request

# Terminal 1: block the local client's address
moon run examples/server -- --block 127.0.0.1
# Terminal 2: paths in the HAProxy configuration are relative to this directory
cd examples/haproxy && haproxy -f haproxy.cfg
# Terminal 3: a matching address should receive 403
curl -i http://127.0.0.1:8080/

#Validation

moon check
moon test                 # native is the module's preferred target
moon test --release
moon info
moon fmt --check
moon doc
moon package --list       # inspect publication contents without uploading

#Limitations

• The agent processes in-flight NOTIFY tasks with serialized writes. Client concurrency requires with_pipelining; negotiation falls back to serialized requests when needed.
• Protocol fragmentation and the SPOP async capability are not implemented. Frames without FIN are rejected with FragmentationNotSupported. This is separate from ordinary transport reads splitting a frame into chunks, which the client handles.
• UDS accept polls at a 5 ms interval. With the declared async dependency, the transport uses a C stub and the public raw_fd API; it does not have an event-driven UDS accept implementation.
• Signed values follow HAProxy's two's-complement-to-UInt64 varint convention; negative values use ten-byte varints.
• See the platform and validation boundaries above before adopting the server in production.

#References and license

• Protocol reference: HAProxy doc/SPOE.txt, SPOE v1.2.
• Varint and typed-data encoding were checked against HAProxy's include/haproxy/intops.h and include/haproxy/spoe.h. This library is an independent implementation.
• Licensed under Apache-2.0; see LICENSE.