README
¶
dataexchange
Data-exchange plugin for the Pilot Protocol daemon. Listens on port 1001
and persists inbound frames under ~/.pilot/: files land in received/
and text/JSON/binary messages land in inbox/.
Install
import "github.com/pilot-protocol/dataexchange"
Usage
f := &dataexchange.Frame{Type: dataexchange.TypeJSON, Payload: body}
if err := dataexchange.WriteFrame(conn, f); err != nil {
return err
}
// Register as a plugin on the daemon runtime:
rt.Register(dataexchange.NewService(dataexchange.ServiceConfig{}))
Layout
| File | What it does |
|---|---|
dataexchange.go |
Wire format: Frame, WriteFrame, ReadFrame, TraceFrame, TypeText/Binary/JSON/File/Trace, TypeName. |
client.go |
Client — Dial and send helpers. |
server.go |
Server — accept loop and handler dispatch. |
service.go |
*Service — coreapi.Service adapter. Build tag !no_dataexchange. |
service_disabled.go |
Stub *Service for -tags no_dataexchange builds. |
Wire format
[4-byte type][4-byte length][payload]
For TypeFile the payload is prefixed with [2-byte name length][name bytes].
For TypeTrace the payload is [4-byte inner_type][8-byte sent_at_ns][inner payload].
Max frame size: 256 MiB.
Build tags
| Tag | Effect |
|---|---|
no_dataexchange |
Compiles a no-op stub whose Start does nothing. Useful for integration tests that don't want inbox files written. |
License
AGPL-3.0-or-later. See LICENSE.
Documentation
¶
Index ¶
- Constants
- func TypeName(t uint32) string
- func WriteFrame(w io.Writer, f *Frame) error
- func WriteTraceFrame(w io.Writer, tf *TraceFrame) error
- type Client
- func (c *Client) Close() error
- func (c *Client) Recv() (*Frame, error)
- func (c *Client) SendBinary(data []byte) error
- func (c *Client) SendFile(name string, data []byte) error
- func (c *Client) SendJSON(data []byte) error
- func (c *Client) SendText(text string) error
- func (c *Client) SendTrace(innerType uint32, data []byte) (sentAtNs int64, err error)
- type Frame
- type Handler
- type Server
- type Service
- type ServiceConfig
- type TraceFrame
Constants ¶
const ( TypeText uint32 = 1 TypeBinary uint32 = 2 TypeJSON uint32 = 3 TypeFile uint32 = 4 // TypeTrace wraps another frame type with nanosecond-precision timing. // Wire layout: [4-byte TypeTrace][4-byte len][4-byte inner_type][8-byte sent_at_ns][inner_payload] TypeTrace uint32 = 5 )
Frame types for data exchange on port 1001.
const MaxFrameSize = 1 << 28
MaxFrameSize caps a single data-exchange frame at 256 MiB. Sized to fit the test fleet's 100 MiB file payloads with margin while still rejecting pathological 500 MiB+ frames that would dominate memory.
Variables ¶
This section is empty.
Functions ¶
func WriteFrame ¶
WriteFrame writes a frame to a writer.
func WriteTraceFrame ¶
func WriteTraceFrame(w io.Writer, tf *TraceFrame) error
WriteTraceFrame serialises a TraceFrame as a TypeTrace outer frame.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client connects to a remote data exchange service on port 1001.
func (*Client) SendBinary ¶
SendBinary sends a binary frame.
type Frame ¶
Frame is a typed data unit exchanged between agents. Wire format: [4-byte type][4-byte length][payload] For TypeFile, payload is: [2-byte name length][name bytes][file data]
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server listens on port 1001 and dispatches incoming frames to a handler.
func (*Server) ListenAndServe ¶
ListenAndServe binds port 1001 and starts accepting connections.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the L11 plugin adapter. Daemon (L7) holds it only as coreapi.Service; cmd/daemon/main.go (L12) constructs it.
func NewService ¶
func NewService(cfg ServiceConfig) *Service
type ServiceConfig ¶
type ServiceConfig struct {
ReceivedDir string
InboxDir string
// IncludeBase64 adds a lossless `data_b64` field to inbox JSON
// alongside `data`. Off by default — only enable when binary
// payloads (e.g. zlib-compressed envelopes) need to round-trip
// without UTF-8 mangling.
IncludeBase64 bool
// InboxMaxFiles caps the number of inbox files retained on disk.
// On exceeding the cap, oldest files (by mtime) are evicted FIFO.
// Zero or negative ⇒ default 10000. Without this cap, a
// misbehaving peer or sustained inbound load fills the operator's
// disk indefinitely.
InboxMaxFiles int
}
ServiceConfig configures the daemon-side dataexchange handler. Both paths default to ~/.pilot/{received,inbox} when empty.
type TraceFrame ¶
TraceFrame carries timing metadata around an inner message frame.
func ReadTracePayload ¶
func ReadTracePayload(f *Frame) (*TraceFrame, error)
ReadTracePayload decodes a TraceFrame from a raw TypeTrace Frame.
Source Files
Directories