User Tools

Site Tools


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

  1. Client sends CONNECT to the Router.

  2. 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.

  3. Router forwards CONNECT to the selected auth server.

  4. Auth server responds with a STATUS message with status 200 OK.

  5. Client sends REQUEST message directly to the auth worker process that responded with the OK status.

  6. Auth worker process performs the request and sends a RESULT message with any result payload

  7. 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


OpenSRF Software Architecture


Transport Subsystem
  • In theory, the transport subsystem can be any communication framework that provides unique, addressable endpoints for client-server communication.
  • XMPP (Jabber) is currently the only supported transport subsystem.

Components common to clients and servers
  • Transport Client - responsible for sending and receiving data on the network, e.g. a jabber client.
  • Transport Handler - responsible for extracting OpenSRF messages from network messages
  • Message Handler - responsible for analyzing OpenSRF messages (e.g. reading message statuses) and dispatching as appropriate.
  • Sessions - Manages a single communication session between a client and a service.

Server-specific Components
  • Method Dispatcher - passes OpenSRF REQUEST messages to the appropriate application plugin.

Application Modules
  • The application business logic will live in one or more application modules/plugins. 
  • Plugins function by registering API names and local method handlers for processing API requests


OpenSRF Server Architecture

For an example server layout, see

osrf-devel/primer.txt · Last modified: 2022/02/10 13:34 by

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.