Document the unix.socket communication protocol

[shanduur]

Hi! So I wanted to understand better how the comms between configuration server and e.g. CLI is supposed to work.

There is no documentation about this. I suppose right now it should work something like:

# 1. Open connection to the UNIX socket
connection = open_unix_socket("unix:///path/to/sozu.sock")

try:
    # 2. Serialize protobuf message
    #    - Object to Byte Array via protobuf libs?
    protobuf_message = create_protobuf_message()
    serialized_message = serialize_protobuf(protobuf_message)

    # 3. Write serialized message to the connection
    connection.write(serialized_message)

    # 4. Read response from the connection
    #    - How is it delimited? Just EOF?
    response_data = connection.read()

    # 5. Deserialize the protobuf message
    #    - Byte Array to Object via protobuf libs?
    deserialized_response = deserialize_protobuf(response_data)

    # Use the deserialized response as needed
    process_response(deserialized_response)

finally:
    # 6. Close the connection
    connection.close()

[Keksoj]

Hi, and firstly thank you for the PR on docker publication, we will look into it ;-)

Your insights on how to write to Sōzu are absolutely valid. Sōzu is thought to function as an API that takes protobuf-serialized messages on a UNIX socket, and returns protobuf-serialized messages on the same socket. The messages are defined in the command_lib

I think the best answer to your need will be the library sozu-client, a library we wrote at Clever Cloud to create side cars to Sōzu. It establishes a connection on the UNIX socket, serializes messages in protobuf, and awaits answers. See the send function

We have not documented an example to use sozu-client. But if you are familiar with Rust, you could create a PR on the sozu-client repository to create a simple client example in a new examples directory.

However, if you wish to use another language than Rust to implement a UNIX+protobuf communication with Sōzu, you would have to do so yourself.

Another idea would be to create a web side-car to Sōzu, by combining sozu-client and a web server in Rust, that would translate between UNIX-protobuf and HTTP-JSON for instance.