-----------------------------------------------

Stream Processing Offload Engine (SPOE)

Version 1.2

( Last update: 2024-07-12 )

-----------------------------------------------

Author : Christopher Faulet

Contact : cfaulet at haproxy dot com

SUMMARY

--------

0. Terms

1. Introduction

2. SPOE configuration

2.1. SPOE scope

2.2. "spoe-agent" section

2.3. "spoe-message" section

2.4. "spoe-group" section

2.5. Example

3. SPOP specification

3.1. Data types

3.2. Frames

3.2.1. Frame capabilities

3.2.2. Frame types overview

3.2.3. Workflow

3.2.4. Frame: HAPROXY-HELLO

3.2.5. Frame: AGENT-HELLO

3.2.6. Frame: NOTIFY

3.2.7. Frame: ACK

3.2.8. Frame: HAPROXY-DISCONNECT

3.2.9. Frame: AGENT-DISCONNECT

3.3. Events & messages

3.4. Actions

3.5. Errors & timeouts

4. Logging

0. Terms

---------

* SPOE : Stream Processing Offload Engine.

A SPOE is a filter talking to servers managed by a SPOA to offload the

stream processing. An engine is attached to a proxy. A proxy can have

several engines. Each engine is linked to an agent and only one.

* SPOA : Stream Processing Offload Agent.

A SPOA is a service that will receive info from a SPOE to offload the

stream processing. An agent manages several servers. It uses a backend to

reference all of them. By extension, these servers can also be called

agents.

* SPOP : Stream Processing Offload Protocol, used by SPOEs to talk to SPOA

servers.

This protocol is used by engines to talk to agents. It is an in-house

binary protocol described in this documentation.

1. Introduction

----------------

SPOE is a feature introduced in HAProxy 1.7. It makes possible the

communication with external components to retrieve some info. The idea started

with the problems caused by most ldap libs not working fine in event-driven

systems (often at least the connect() is blocking). So, it is hard to properly

implement Single Sign On solution (SSO) in HAProxy. The SPOE will ease this

kind of processing, or we hope so.

The aim of SPOE is to allow any kind of offloading on the streams. It can

offload the processing before "tcp-request content", "tcp-response content",

"http-request" and "http-response" rules. It is also possible to offload the

processing via an TCP/HTTP rule.

Some example implementations in various languages are linked to from the

HAProxy Wiki page dedicated to this mechanism:

https://github.com/haproxy/wiki/wiki/SPOE:-Stream-Processing-Offloading-Engine

2. SPOE configuration

----------------------

Because SPOE is implemented as a filter, To use it, a "filter spoe" line must

be declared xin a proxy section (frontend/backend/listen) :

frontend my-front

...

filter spoe [engine <name>] config <file>

...

The "config" parameter is mandatory. It specifies the SPOE configuration

file. The engine name is optional. It can be set to declare the scope to use in

the SPOE configuration. So it is possible to use the same SPOE configuration

for several engines. If no name is provided, the SPOE configuration must not

contain any scope directive.

Using a separate configuration file makes possible to disable completely an

engine by only commenting the SPOE filter line, including the parsing of

sections reserved to SPOE. This is also a way to keep the HAProxy configuration

clean.

A SPOE configuration file must contains, at least, the SPOA configuration

("spoe-agent" section) and SPOE messages/groups ("spoe-message" or "spoe-group"

sections) attached to this agent.

IMPORTANT : The configuration of a SPOE filter must be located in a dedicated

file. But the backend used by a SPOA must be declared in HAProxy configuration

file.

2.1. SPOE scope

-------------------------

If an engine name is specified on the SPOE filter line, then the corresponding

scope must be defined in the SPOE configuration with the same name. It is

possible to have several SPOE scopes in the same file. In each scope, one and

only one "spoe-agent" section must be defined, to configure the SPOA linked to

the defined engine and several "spoe-message" and "spoe-group" sections to

describe, respectively, messages and group of messages sent to servers managed

the SPOA.

A SPOE scope starts with this kind of line :

[<name>]

where <name> is the same engine name specified on the SPOE filter line. The

scope ends when the file ends or when another scope is found.

Example :

[my-first-engine]

spoe-agent my-agent

...

spoe-message msg1

...

spoe-message msg2

...

spoe-group grp1

...

spoe-group grp2

...

[my-second-engine]

...

If no engine name is provided on the SPOE filter line, no SPOE scope must be

found in the SPOE configuration file. All the file is considered to be in the

same anonymous and implicit scope.

The engine name must be unique for a proxy. If no engine name is provided on

the SPOE filter line, the SPOE agent name is used by default.

2.2. "spoe-agent" section

--------------------------

For each engine, exactly one "spoe-agent" section must be defined. Enabled SPOE

messages are declared in this section, and all the parameters (timeout,

options, ...) used to customize the agent behavior.

spoe-agent <name>

Create a new SPOA with the name <name>. It must have one and only one

"spoe-agent" definition by SPOE scope.

Arguments :

<name> is the name of the agent section.

following keywords are supported :

- groups

- log

- max-frame-size

- messages

- [no] option dontlog-normal

- [no] option pipelining

- option continue-on-error

- option force-set-var

- option set-on-error

- option set-process-time

- option set-total-time

- option var-prefix

- register-var-names

- timeout processing

- use-backend

following keywords are deprecated and ignored:

- maxconnrate

- maxerrrate

- max-waiting-frames

- [no] option async

- [no] option send-frag-payload

- timeout hello|idle

groups <grp-name> ...

Declare the list of SPOE groups that an agent will handle.

Arguments :

<grp-name> is the name of a SPOE group.

Groups declared here must be found in the same engine scope, else an error is

triggered during the configuration parsing. Several "groups" lines can be

defined.

See also: "spoe-group" section.

log global

log <address> [len <length>] [format <format>] <facility> [<level> [<minlevel>]]

no log

Enable per-instance logging of events and traffic.

Prefix :

no should be used when the logger list must be flushed.

See the HAProxy Configuration Manual for details about this option.

maxconnrate <number> [DEPRECATED]

Set the maximum number of connections per second to <number>. The SPOE will

stop to open new connections if the maximum is reached and will wait to

acquire an existing one. So it is important to set "timeout hello" to a

relatively small value.

This parameter is now deprecated and ignored. It will be removed in future

versions.

maxerrrate <number> [DEPRECATED]

Set the maximum number of errors per second to <number>. The SPOE will stop

its processing if the maximum is reached.

This parameter is now deprecated and ignored. It will be removed in future

versions.

max-frame-size <number>

Set the maximum allowed size for frames exchanged between HAProxy and SPOA.

It must be in the range [256, tune.bufsize-4] (4 bytes are reserved for the

frame length). By default, it is set to (tune.bufsize-4).

max-waiting-frames <number> [DEPRECATED]

Set the maximum number of frames waiting for an acknowledgement on the same

connection. This value is only used when the pipelinied or asynchronous

exchanges between HAProxy and SPOA are enabled. By default, it is set to 20.

This parameter is now deprecated and ignored. It will be removed in future

versions.

messages <msg-name> ...

Declare the list of SPOE messages that an agent will handle.

Arguments :

<msg-name> is the name of a SPOE message.

Messages declared here must be found in the same engine scope, else an error

is triggered during the configuration parsing. Several "messages" lines can

be defined.

See also: "spoe-message" section.

option async [DEPRECATED]

no option async

Enable or disable the support of asynchronous exchanges between HAProxy and

SPOA. By default, this option is enabled.

This parameter is now deprecated and ignored. It will be removed in future

versions.

option continue-on-error

Do not stop the events processing when an error occurred on a stream.

By default, for a specific stream, when an abnormal/unexpected error occurs,

the SPOE is disabled for all the transaction. if several events are

configured, such error on an event will disabled all following. For TCP

streams, this will disable the SPOE for the whole session. For HTTP streams,

this will disable it for the transaction (request and response).

When set, this option bypass this behaviour and only the current event will

be ignored.

option dontlog-normal

no option dontlog-normal

Enable or disable logging of normal, successful processing.

Arguments : none

See also: "log" and section 4 about logging.

option force-set-var

By default, SPOE filter only register already known variables (mainly from

parsing of the configuration), and process-wide variables (those of scope

"proc") cannot be created. If HAProxy trusts the agent and registers all

variables (ex: can be useful for LUA workload), this option can be sets.

Caution : this option opens to a variety of attacks such as a rogue SPOA that

asks to register too many variables.

option pipelining

no option pipelining

Enable or disable the support of pipelined exchanges between HAProxy and

SPOA. By default, this option is enabled.

option send-frag-payload [DEPRECATED]

no option send-frag-payload

Enable or disable the sending of fragmented payload to SPOA. By default, this

option is enabled.

This parameter is now deprecated and ignored. It will be removed in future

versions.

option set-on-error <var name>

Define the variable to set when an error occurred during an event processing.

Arguments :

<var name> is the variable name, without the scope. The name may only

contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

This variable will only be set when an error occurred in the scope of the

transaction. As for all other variables define by the SPOE, it will be

prefixed. So, if the variable name is "error" and the prefix is

"my_spoe_pfx", the variable will be "txn.my_spoe_pfx.error".

When set, the variable is an integer representing the error reason. For values

under 256, it represents an error coming from the engine. Below 256, it

reports a SPOP error. In this case, to retrieve the right SPOP status code,

256 must be removed from this value. Here are possible values:

* 1 a timeout occurred during the event processing.

* 2 an error was triggered during the resources allocation.

* 3 the frame payload exceeds the frame size and it cannot be

fragmented.

* 4 the fragmentation of a payload is aborted.

* 5 The frame processing has been interrupted by HAProxy.

* 255 an unknown error occurred during the event processing.

* 256+N a SPOP error occurred during the event processing (see section

"Errors & timeouts").

Note that if "option continue-on-error" is set, the variable is not

automatically removed between events processing.

See also: "option continue-on-error", "option var-prefix".

option set-process-time <var name>

Define the variable to set to report the processing time of the last event or

group.

Arguments :

<var name> is the variable name, without the scope. The name may only

contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

This variable will be set in the scope of the transaction. As for all other

variables define by the SPOE, it will be prefixed. So, if the variable name

is "process_time" and the prefix is "my_spoe_pfx", the variable will be

"txn.my_spoe_pfx.process_time".

When set, the variable is an integer representing the delay to process the

event or the group, in milliseconds. From the stream point of view, it is the

latency added by the SPOE processing for the last handled event or group.

If several events or groups are processed for the same stream, this value

will be overridden.

See also: "option set-total-time".

option set-total-time <var name>

Define the variable to set to report the total processing time SPOE for a

stream.

Arguments :

<var name> is the variable name, without the scope. The name may only

contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

This variable will be set in the scope of the transaction. As for all other

variables define by the SPOE, it will be prefixed. So, if the variable name

is "total_time" and the prefix is "my_spoe_pfx", the variable will be

"txn.my_spoe_pfx.total_time".

When set, the variable is an integer representing the sum of processing times

for a stream, in milliseconds. From the stream point of view, it is the

latency added by the SPOE processing.

If several events or groups are processed for the same stream, this value

will be updated.

See also: "option set-process-time".

option var-prefix <prefix>

Define the prefix used when variables are set by an agent.

Arguments :

<prefix> is the prefix used to limit the scope of variables set by an

agent.

To avoid conflict with other variables defined by HAProxy, all variables

names will be prefixed. By default, the "spoe-agent" name is used. This

option can be used to customize it.

The prefix will be added between the variable scope and its name, separated

by a '.'. It may only contain characters 'a-z', 'A-Z', '0-9', '.' and '_', as

for variables name. In HAProxy configuration, this prefix must be used as a

part of the variables name. For example, if an agent define the variable

"myvar" in the "txn" scope, with the prefix "my_spoe_pfx", then

"txn.my_spoe_pfx.myvar" name must be used in HAProxy configuration.

By default, an agent will never set new variables at runtime: It can only set

new value for existing ones. To change this behaviour, see "force-set-var"

option and "register-var-names" directive.

register-var-names <var name> ...

Register some variable names. By default, an agent will not be allowed to set

new variables at runtime. This rule can be totally relaxed by setting the

option "force-set-var". If all the required variables are known, this

directive is a good way to register them without letting an agent doing what

it want. This is only required if these variables are not referenced anywhere

in the HAProxy configuration or the SPOE one.

Arguments:

<var name> is a variable name without the scope. The name may only

contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

The prefix will be automatically added during the registration. Several

"register-var-names" lines can be used.

See also: "option force-set-var", "option var-prefix".

timeout hello <timeout> [DEPRECATED]

Set the maximum time to wait for an agent to receive the AGENT-HELLO frame.

It is applied on the stream that handle the connection with the agent.

Arguments :

<timeout> is the timeout value specified in milliseconds by default, but

can be in any other unit if the number is suffixed by the unit,

as explained at the top of this document.

This timeout is an applicative timeout. It differ from "timeout connect"

defined on backends.

This parameter is now deprecated and ignored. It will be removed in future

versions.

timeout idle <timeout> [DEPRECATED]

Set the maximum time to wait for an agent to close an idle connection. It is

applied on the stream that handle the connection with the agent.

Arguments :

<timeout> is the timeout value specified in milliseconds by default, but

can be in any other unit if the number is suffixed by the unit,

as explained at the top of this document.

This parameter is now deprecated and ignored. It will be removed in future

versions.

timeout processing <timeout>

Set the maximum time to wait for a stream to process an event, i.e to acquire

a stream to talk with an agent, to encode all messages, to send the NOTIFY

frame, to receive the corresponding acknowledgement and to process all

actions. It is applied on the stream that handle the client and the server

sessions.

Arguments :

<timeout> is the timeout value specified in milliseconds by default, but

can be in any other unit if the number is suffixed by the unit,

as explained at the top of this document.

use-backend <backend>

Specify the backend to use. It must be defined.

Arguments :

<backend> is the name of a valid "backend" section.

2.3. "spoe-message" section

----------------------------

To offload the stream processing, SPOE will send messages with specific

information at a specific moment in the stream life and will wait for

corresponding replies to know what to do.

spoe-message <name>

Create a new SPOE message with the name <name>.

Arguments :

<name> is the name of the SPOE message.

Here a message that can be referenced in a "spoe-agent" section is

defined. Following keywords are supported :

- acl

- args

- event

See also: "spoe-agent" section.

acl <aclname> <criterion> [flags] [operator] <value> ...

Declare or complete an access list.

See section 7 about ACL usage in the HAProxy Configuration Manual.

args [name=]<sample> ...

Define arguments passed into the SPOE message.

Arguments :

<sample> is a sample expression.

When the message is processed, if a sample expression is not available, it is

set to NULL. Arguments are processed in their declaration order and added in

the message in that order. It is possible to declare named arguments.

For example:

args frontend=fe_id src dst

event <name> [ { if | unless } <condition> ]

Set the event that triggers sending of the message. It may optionally be

followed by an ACL-based condition, in which case it will only be evaluated

if the condition is true. A SPOE message can only be sent on one event. If

several events are defined, only the last one is considered.

ACL-based conditions are executed in the context of the stream that handle

the client and the server connections.

Arguments :

<name> is the event name.

<condition> is a standard ACL-based condition.

Supported events are:

- on-client-session

- on-server-session

- on-frontend-tcp-request

- on-switching-rules

- on-backend-tcp-request

- on-tcp-response

- on-frontend-http-request

- on-backend-http-request

- on-http-response

See section "Events & Messages" for more details about supported events.

See section 7 about ACL usage in the HAProxy Configuration Manual.

2.4. "spoe-group" section

--------------------------

This section can be used to declare a group of SPOE messages. Unlike messages

referenced in a "spoe-agent" section, messages inside a group are not sent on a

specific event. The sending must be triggered by TCP or HTTP rules, from the

HAProxy configuration.

spoe-group <name>

Create a new SPOE group with the name <name>.

Arguments :

<name> is the name of the SPOE group.

Here a group of SPOE messages is defined. It can be referenced in a

"spoe-agent" section. Following keywords are supported :

- messages

See also: "spoe-agent" and "spoe-message" sections.

messages <msg-name> ...

Declare the list of SPOE messages belonging to the group.

Arguments :

<msg-name> is the name of a SPOE message.

Messages declared here must be found in the same engine scope, else an error

is triggered during the configuration parsing. Furthermore, a message belongs

at most to a group. Several "messages" lines can be defined.

See also: "spoe-message" section.

2.5. Example

-------------

Here is a simple but complete example that sends client-ip address to a ip

reputation service. This service can set the variable "ip_score" which is an

integer between 0 and 100, indicating its reputation (100 means totally safe

and 0 a blacklisted IP with no doubt).

###

### HAProxy configuration

frontend www

mode http

bind *:80

filter spoe engine ip-reputation config spoe-ip-reputation.conf

# Reject connection if the IP reputation is under 20

tcp-request content reject if { var(sess.iprep.ip_score) -m int lt 20 }

default_backend http-servers

backend http-servers

mode http

server http A.B.C.D:80

backend iprep-servers

mode spop

balance roundrobin

timeout connect 5s # greater than hello timeout

timeout server 3m # greater than idle timeout

server iprep1 A1.B1.C1.D1:12345

server iprep2 A2.B2.C2.D2:12345

####

### spoe-ip-reputation.conf

[ip-reputation]

spoe-agent iprep-agent

messages get-ip-reputation

option var-prefix iprep

timeout processing 10ms

use-backend iprep-servers

spoe-message get-ip-reputation

args ip=src

event on-client-session if ! { src -f /etc/haproxy/whitelist.lst }

3. SPOP specification

----------------------

3.1. Data types

----------------

Here is the bytewise representation of typed data:

TYPED-DATA : <TYPE:4 bits><FLAGS:4 bits><DATA>

Supported types and their representation are:

TYPE | ID | DESCRIPTION

-----------------------------+-----+----------------------------------

NULL | 0 | NULL : <0>

Boolean | 1 | BOOL : <1+FLAG>

32bits signed integer | 2 | INT32 : <2><VALUE:varint>

32bits unsigned integer | 3 | UINT32 : <3><VALUE:varint>

64bits signed integer | 4 | INT64 : <4><VALUE:varint>

32bits unsigned integer | 5 | UNIT64 : <5><VALUE:varint>

IPV4 | 6 | IPV4 : <6><STRUCT IN_ADDR:4 bytes>

IPV6 | 7 | IPV6 : <7><STRUCT IN_ADDR6:16 bytes>

String | 8 | STRING : <8><LENGTH:varint><BYTES>

Binary | 9 | BINARY : <9><LENGTH:varint><BYTES>

10 -> 15 unused/reserved | - | -

-----------------------------+-----+----------------------------------

Variable-length integer (varint) are encoded using Peers encoding:

0 <= X < 240 : 1 byte (7.875 bits) [ XXXX XXXX ]

240 <= X < 2288 : 2 bytes (11 bits) [ 1111 XXXX ] [ 0XXX XXXX ]

2288 <= X < 264432 : 3 bytes (18 bits) [ 1111 XXXX ] [ 1XXX XXXX ] [ 0XXX XXXX ]

264432 <= X < 33818864 : 4 bytes (25 bits) [ 1111 XXXX ] [ 1XXX XXXX ]*2 [ 0XXX XXXX ]

33818864 <= X < 4328786160 : 5 bytes (32 bits) [ 1111 XXXX ] [ 1XXX XXXX ]*3 [ 0XXX XXXX ]

...

For booleans, the value (true or false) is the first bit in the FLAGS

bitfield. if this bit is set to 0, then the boolean is evaluated as false,

otherwise, the boolean is evaluated as true.

3.2. Frames

------------

Exchange between HAProxy and agents are made using FRAME packets. All frames

must be prefixed with their size encoded on 4 bytes in network byte order:

<FRAME-LENGTH:4 bytes> <FRAME>

A frame always starts with its type, on one byte, followed by metadata

containing flags, on 4 bytes and a two variable-length integer representing the

stream identifier and the frame identifier inside the stream:

FRAME : <FRAME-TYPE:1 byte> <METADATA> <FRAME-PAYLOAD>

METADATA : <FLAGS:4 bytes> <STREAM-ID:varint> <FRAME-ID:varint>

Then comes the frame payload. Depending on the frame type, the payload can be

of three types: a simple key/value list, a list of messages or a list of

actions.

FRAME-PAYLOAD : <LIST-OF-MESSAGES> | <LIST-OF-ACTIONS> | <KV-LIST>

LIST-OF-MESSAGES : [ <MESSAGE-NAME> <NB-ARGS:1 byte> <KV-LIST> ... ]

MESSAGE-NAME : <STRING>

LIST-OF-ACTIONS : [ <ACTION-TYPE:1 byte> <NB-ARGS:1 byte> <ACTION-ARGS> ... ]

ACTION-ARGS : [ <TYPED-DATA>... ]

KV-LIST : [ <KV-NAME> <KV-VALUE> ... ]

KV-NAME : <STRING>

KV-VALUE : <TYPED-DATA>

FLAGS :

Flags are a 32 bits field. They are encoded on 4 bytes in network byte

order, where the bit 0 is the LSB.

0 1 2-31

+---+---+----------+

| | A | |

| F | B | |

| I | O | RESERVED |

| N | R | |

| | T | |

+---+---+----------+

FIN: Indicates that this is the final payload fragment. The first fragment

may also be the final fragment. The payload fragmentation was removed

and is now deprecated. It means the FIN flag must be set on all

frames.

ABORT: Indicates that the processing of the current frame must be

cancelled.

Frames cannot exceed a maximum size negotiated between HAProxy and agents

during the HELLO handshake. Most of time, payload will be small enough to send

it in one frame.

IMPORTANT : The maximum size supported by peers for a frame must be greater

than or equal to 256 bytes. A good common value is the HAProxy

buffer size minus 4 bytes, reserved for the frame length

(tune.bufsize - 4). It is the default value announced by HAproxy.

3.2.1. Frame capabilities

--------------------------

Here are the list of official capabilities that HAProxy and agents can support:

* pipelining: This is the ability for a peer to decouple NOTIFY and ACK

frames. This is a symmectical capability. To be used, it must

be supported by HAProxy and agents. Unlike HTTP pipelining, the

ACK frames can be send in any order, but always on the same TCP

connection used for the corresponding NOTIFY frame.

Unsupported or unknown capabilities are silently ignored, when possible.

NOTE: Fragmentation and async capabilities were deprecated and are now ignored.

3.2.2. Frame types overview

----------------------------

Here are types of frame supported by SPOE. Frames sent by HAProxy come first,

then frames sent by agents :

TYPE | ID | DESCRIPTION

-----------------------------+-----+-------------------------------------

HAPROXY-HELLO | 1 | Sent by HAProxy when it opens a

| | connection on an agent.

| |

HAPROXY-DISCONNECT | 2 | Sent by HAProxy when it want to close

| | the connection or in reply to an

| | AGENT-DISCONNECT frame

| |

NOTIFY | 3 | Sent by HAProxy to pass information

| | to an agent

-----------------------------+-----+-------------------------------------

AGENT-HELLO | 101 | Reply to a HAPROXY-HELLO frame, when

| | the connection is established

| |

AGENT-DISCONNECT | 102 | Sent by an agent just before closing

| | the connection

| |

ACK | 103 | Sent to acknowledge a NOTIFY frame

-----------------------------+-----+-------------------------------------

Unknown frames may be silently skipped or trigger an error, depending on the

implementation.

3.2.3. Workflow

----------------

* Successful HELLO handshake:

HAPROXY AGENT SRV

| HAPROXY-HELLO |

| (healthcheck: false) |

| --------------------------> |

| |

| AGENT-HELLO |

| <-------------------------- |

| |

* Successful HELLO healthcheck:

HAPROXY AGENT SRV

| HAPROXY-HELLO |

| (healthcheck: true) |

| --------------------------> |

| |

| AGENT-HELLO + close() |

| <-------------------------- |

| |

* Error encountered by agent during the HELLO handshake:

HAPROXY AGENT SRV

| HAPROXY-HELLO |

| --------------------------> |

| |

| DISCONNECT + close() |

| <-------------------------- |

| |

* Error encountered by HAProxy during the HELLO handshake:

HAPROXY AGENT SRV

| HAPROXY-HELLO |

| --------------------------> |

| |

| AGENT-HELLO |

| <-------------------------- |

| |

| DISCONNECT |

| --------------------------> |

| |

| DISCONNECT + close() |

| <-------------------------- |

| |

* Notify / Ack exchange (unfragmented payload):

HAPROXY AGENT SRV

| NOTIFY |

| --------------------------> |

| |

| ACK |

| <-------------------------- |

| |

* Connection closed by haproxy:

HAPROXY AGENT SRV

| DISCONNECT |

| --------------------------> |

| |

| DISCONNECT + close() |

| <-------------------------- |

| |

* Connection closed by agent:

HAPROXY AGENT SRV

| DISCONNECT + close() |

| <-------------------------- |

| |

3.2.4. Frame: HAPROXY-HELLO

----------------------------

This frame is the first one exchanged between HAProxy and an agent, when the

connection is established. The payload of this frame is a KV-LIST. STREAM-ID

and FRAME-ID are must be set 0.

Following items are mandatory in the KV-LIST:

* "supported-versions" <STRING>

Last SPOP major versions supported by HAProxy. It is a comma-separated list

of versions, following the format "Major.Minor". Spaces must be ignored, if

any. When a major version is announced by HAProxy, it means it also support

all previous minor versions.

Example: "2.0, 1.5" means HAProxy supports SPOP 2.0 and 1.0 to 1.5

* "max-frame-size" <UINT32>

This is the maximum size allowed for a frame. The HAPROXY-HELLO frame must

be lower or equal to this value.

* "capabilities" <STRING>

This a comma-separated list of capabilities supported by HAProxy. Spaces

must be ignored, if any.

Following optional items can be added in the KV-LIST:

* "healthcheck" <BOOLEAN>

If this item is set to TRUE, then the HAPROXY-HELLO frame is sent during a

SPOE health check. When set to FALSE, this item can be ignored.

* "engine-id" <STRING>

This is a uniq string that identify a SPOE engine.

To finish the HELLO handshake, the agent must return an AGENT-HELLO frame with

its supported SPOP version, the lower value between its maximum size allowed

for a frame and the HAProxy one and capabilities it supports. If an error

occurs or if an incompatibility is detected with the agent configuration, an

AGENT-DISCONNECT frame must be returned.

3.2.5. Frame: AGENT-HELLO

--------------------------

This frame is sent in reply to a HAPROXY-HELLO frame to finish a HELLO

handshake. As for HAPROXY-HELLO frame, STREAM-ID and FRAME-ID are also set

0. The payload of this frame is a KV-LIST.

Following items are mandatory in the KV-LIST:

* "version" <STRING>

This is the SPOP version the agent supports. It must follow the format

"Major.Minor" and it must be lower or equal than one of major versions

announced by HAProxy.

* "max-frame-size" <UINT32>

This is the maximum size allowed for a frame. It must be lower or equal to

the value in the HAPROXY-HELLO frame. This value will be used for all

subsequent frames.

* "capabilities" <STRING>

This a comma-separated list of capabilities supported by agent. Spaces must

be ignored, if any.

At this time, if everything is ok for HAProxy (supported version and valid

max-frame-size value), the HELLO handshake is successfully completed. Else,

HAProxy sends a HAPROXY-DISCONNECT frame with the corresponding error.

If "healthcheck" item was set to TRUE in the HAPROXY-HELLO frame, the agent can

safely close the connection without DISCONNECT frame. In all cases, HAProxy

will close the connection at the end of the health check.

3.2.6. Frame: NOTIFY

---------------------

Information are sent to the agents inside NOTIFY frames. These frames are

attached to a stream, so STREAM-ID and FRAME-ID must be set. The payload of

NOTIFY frames is a LIST-OF-MESSAGES.

NOTIFY frames must be acknowledge by agents sending an ACK frame, repeating

right STREAM-ID and FRAME-ID.

3.2.7. Frame: ACK

------------------

ACK frames must be sent by agents to reply to NOTIFY frames. STREAM-ID and

FRAME-ID found in a NOTIFY frame must be reuse in the corresponding ACK

frame. The payload of ACK frames is a LIST-OF-ACTIONS.

3.2.8. Frame: HAPROXY-DISCONNECT

---------------------------------

If an error occurs, at anytime, from the HAProxy side, a HAPROXY-DISCONNECT

frame is sent with information describing the error. HAProxy will wait an

AGENT-DISCONNECT frame in reply. All other frames will be ignored. The agent

must then close the socket.

The payload of this frame is a KV-LIST. STREAM-ID and FRAME-ID are must be set

0.

Following items are mandatory in the KV-LIST:

* "status-code" <UINT32>

This is the code corresponding to the error.

* "message" <STRING>

This is a textual message describing the error.

For more information about known errors, see section "Errors & timeouts"

3.2.9. Frame: AGENT-DISCONNECT

-------------------------------

If an error occurs, at anytime, from the agent size, a AGENT-DISCONNECT frame

is sent, with information describing the error. such frame is also sent in reply

to a HAPROXY-DISCONNECT. The agent must close the socket just after sending

this frame.

The payload of this frame is a KV-LIST. STREAM-ID and FRAME-ID are must be set

0.

Following items are mandatory in the KV-LIST:

* "status-code" <UINT32>

This is the code corresponding to the error.

* "message" <STRING>

This is a textual message describing the error.