OpenSRF Protocol
The Primary Players
OpenSRF Service – Takes requests, performs some type of process, and responds to the the client.
OpenSRF Client – Sends requests to OpenSRF services. A client may be a standalone client or a client that runs as part of a service, sending requests to yet another service.
Jabber Server - All network communication takes the form of Jabber messages which go through the jabber server for delivery to the recipient.
OpenSRF Router – When a client begins communication with an OpenSRF service, the initial message goes to the OpenSRF Router so that it may be delivered to the next service instance in the service pool. The Router also ensures that message delivery failures are re-routed to the next available service.
Message Types
CONNECT – Initiates a stateful session to a service
DISCONNECT – Terminates a stateful session to a service
REQUEST – Sends an API request to a service
RESULT – Delivers API response from service to client
STATUS – Carries OpenSRF status information
Common Statuses
100 Continue – Tells the client to reset its receive timeout
200 OK – Indicates a successful CONNECT attempt
205 COMPLETE – Indicates all responses to a request have been sent
404 NOT FOUND – Indicates requested API call does not exist
408 TIMEOUT – Indicates the stateful session has been terminated by the server due to client timeout.
500 SERVER ERROR – Indicates a server error
505 VERSION NOT SUPPORTED – Indicates the API level of the request is not supported
Communication Types
Stateful – A client initiates a stateful connection by sending a CONNECT message to the service. After a successful connection is initiated, the client communicates directly with the service's worker process for the duration of the session. When the client has completed its requests, it sends a DISCONNECT message to close out the session. This type of communication is especially useful for multi-request database transactions. With stateful communication, only the first message (CONNECT) is delivered through the Jabber Router. Future communication takes place directly between the client and the worker process of the service. This is similar to HTTP Keepalive sessions.
Stateless – No CONNECT message is issued. A client simply sends a REQUEST message directly to the service. When a client operates in stateless mode, all REQUEST messages to services are delivered through the Jabber Router.
Example communication – stateful request to an authentication service
Client sends CONNECT to the Router.
Router looks up next server in the auth service server pool. For example, there could be 5 auth servers registered with the router. The next one in line gets the request.
Router forwards CONNECT to the selected auth server.
Auth server responds with a STATUS message with status 200 OK.
Client sends REQUEST message directly to the auth worker process that responded with the OK status.
Auth worker process performs the request and sends a RESULT message with any result payload
Client sends a DISCONNECT to the auth worker process to terminate the session. Note that if the client neglected to send a DISCONNECT message, the auth server process would have responded with a STATUS 408 TIMEOUT after the configured amount of time.
Keep in mind that every message that goes over the network is delivered by the Jabber server. From a physical layer perspective, the first CONNECT/STATUS message pair would look like client -> jabber -> router -> jabber -> service, service -> jabber -> client
