Circuits

To actually transmit messages we need to establish circuits between PSYC nodes. A PSYC node consists of an entity, the root. Circuits provide reliable message transfer.

TCP circuits

To establish a TCP circuit you need to connect to a remote endpoint of a PSYC node. The endpoint is described by an uniform.

If you are the initiating node you will find the other endpoint by looking at the hostname of the uniform of the PSYC node you want to establish a circuit to. (The default listening port is 4404).

Endpoint uniforms

In the following negotiation the uniforms in _source and _target are uniforms of 'protocol roots' (see Spec:Glossary).

You are the client side

After the connection is established you have to send an empty packet. You wait for the server to send an empty packet, too. If that arrives, you send a client hello message _request_circuit. This message must contain the _source (your address) and _target (the address of the node you want to connect to. It may optionally contain a psyc list variable describing your capabilities (compression, tls)).

Then you wait for the reply to the _request_circuit. Usually, the server will reply with a _notice_circuit_established message. The _target of that message should be the _source of your original request and vice-versa. The server may require negotiation of certain features (tls, compression) before it will grant you a _notice_circuit_established.

TODO: work out protocol for tls and compression negotiation. TODO: For message tracking see different specification about _tag/_tag_reply (TODO!). NOTE: client side hello containing capabilites is better than

     xmpp way which makes it necessary for server to indicate required features

NOTE: When you received _notice_circuit_established, you may want to start to flush your queued packets.

You are on the server side

When the connection to the client is established and you received an empty packet you send an empty packet back.

The client will send a _request_circuit in response. This contains his host (_source) and what he thinks that your name is (_target).

If you don't think that you are _target, you should deny circuit creation with _error_request_circuit_unknown_host.

The request my contain a list of client capabilities. If you want to enforce negotiation of any of those, you may do so before replying with _notice_circuit_established.

You must check that the originator of the circuit may send for the address he claims to open the circuit for. usually this check is done by checking "ip address of client == dns lookup of _source host", but may also be accomplished by means of x509 certificates or xmppish dialback