Differences

This shows you the differences between two versions of the page.

--- osrf-devel:primer [2007/04/16 09:10] – created phasefx
+++ osrf-devel:primer [2022/02/10 13:34] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+<html>
+<div style="padding: 8px; background-color: white">
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="4">OpenSRF Protocol<br/>
+  </font>
+</p>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="4"><br/>
+  </font>
+</p>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="3">The Primary Players</font>
+</p>
+<ul>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>OpenSRF Service </b>– Takes
+      requests, performs some type of process, and responds to the the
+      client.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>OpenSRF Client</b> – 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.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>Jabber Server</b> - All network
+      communication takes the form of Jabber messages which go through the
+      jabber server for delivery to the recipient.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>OpenSRF Router</b> – 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.&nbsp; The Router also ensures that message
+      delivery failures are re-routed to the next available service.</font>
+    </p>
+  </li>
+</ul>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="3">Message Types</font>
+</p>
+<ul>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>CONNECT</b> – Initiates a
+      stateful session to a service</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>DISCONNECT</b> – Terminates a
+      stateful session to a service</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>REQUEST</b> – Sends an API
+      request to a service</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>RESULT</b> – Delivers API
+      response from service to client</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>STATUS</b> – Carries OpenSRF
+      status information</font>
+    </p>
+  </li>
+</ul>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="3">Common Statuses</font>
+</p>
+<ul>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>100 Continue</b> – Tells the
+      client to reset its receive timeout</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>200 OK</b> – Indicates a
+      successful CONNECT attempt</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>205 COMPLETE</b> – Indicates all
+      responses to a request have been sent</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>404 NOT FOUND</b> – Indicates
+      requested API call does not exist</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>408 TIMEOUT</b> – Indicates the
+      stateful session has been terminated by the server due to client
+      timeout.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>500 SERVER ERROR</b> – Indicates
+      a server error</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>505 VERSION NOT SUPPORTED</b> –
+      Indicates the API level of the request is not supported</font>
+    </p>
+  </li>
+</ul>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="3">Communication Types</font>
+</p>
+<ul>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>Stateful</b> – 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.&nbsp; This is similar to HTTP Keepalive sessions.
+      </font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt"><b>Stateless</b> – 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.</font>
+    </p>
+  </li>
+</ul>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <font size="3">Example communication – </font><font size="3">stateful request
+  to an authentication service</font>
+</p>
+<ol>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">Client sends CONNECT to the
+      Router.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">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.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">Router forwards CONNECT to the
+      selected auth server.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">Auth server responds with a STATUS
+      message with status 200 OK.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">Client sends REQUEST message
+      directly to the auth worker process that responded with the OK
+      status.</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">Auth worker process performs the
+      request and sends a RESULT message with any result payload</font>
+    </p>
+  </li>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">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.
+      </font>
+    </p>
+  </li>
+</ol>
+<p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+  <br/>
+</p>
+<ul>
+  <li>
+    <p style="MARGIN-BOTTOM:0in; LINE-HEIGHT:150%">
+      <font size="2" style="FONT-SIZE:10pt">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 -&gt; jabber -&gt; router -&gt; jabber -&gt; service, service -&gt;
+      jabber -&gt; client</font>
+    </p>
+  </li>
+</ul>
+<br/>
+------------------------------------------------------------------------------------------------<br/>
+<br/>
+OpenSRF Software Architecture<br/>
+<br/>
+<font size="3">See
+</font><a href="http://open-ils.org/documentation/OpenILS_Structural_Overview.png" title="http://open-ils.org/documentation/OpenILS_Structural_Overview.png">http://open-ils.org/documentation/OpenILS_Structural_Overview.png</a><br/>
+<br/>
+<font size="3">Transport Subsystem<br/>
+</font>
+<ul>
+  <li>
+    <font size="3"> I<font size="2">n theory, the transport subsystem can be any
+    communication framework that provides unique, addressable endpoints for
+    client-server communication.<br/>
+    </font></font>
+  </li>
+  <li>
+    <font size="2">XMPP (Jabber) is currently the only supported transport
+    subsystem.</font><br/>
+  </li>
+</ul>
+<br/>
+<font size="3"><font size="3">Components common to clients and
+servers</font><br/>
+</font>
+<ul>
+  <li>
+    <font size="2"> Transport Client - responsible for sending and receiving
+    data on the network, e.g. a jabber client.<br/>
+    </font>
+  </li>
+  <li>
+    <font size="2"> Transport Handler - responsible for extracting OpenSRF
+    messages from network messages<br/>
+    </font>
+  </li>
+  <li>
+    <font size="2"> Message Handler - responsible for analyzing OpenSRF messages
+    (e.g. reading message statuses) and dispatching as appropriate. </font>
+  </li>
+  <li>
+    <font size="2"> Sessions - Manages a single communication session between a
+    client and a service.</font><br/>
+  </li>
+</ul>
+<br/>
+<font size="3">Server-specific Components<br/>
+</font>
+<ul>
+  <li>
+    <font size="2"> Method Dispatcher - passes OpenSRF REQUEST messages to the
+    appropriate application plugin.</font>
+  </li>
+</ul>
+<br/>
+<font size="3">Application Modules<br/>
+</font>
+<ul>
+  <li>
+    <font size="2">The application business logic will live in one or more
+    application modules/plugins.&nbsp;<br/>
+    </font>
+  </li>
+  <li>
+    <font size="2">Plugins function by registering API names and local method
+    handlers for processing API requests<br/>
+    </font>
+  </li>
+</ul>
+<br/>
+------------------------------------------------------------------------------------------------<br/>
+<br/>
+OpenSRF Server Architecture<br/>
+<br/>
+<font size="3">For an example server layout, see
+</font><a href="http://open-ils.org/documentation/OpenSRF_Server_Architecture.jpg" title="http://open-ils.org/documentation/OpenSRF_Server_Architecture.jpg">http://open-ils.org/documentation/OpenSRF_Server_Architecture.jpg</a><br/>
+<br/>
+<br/>
+<br/>
+<br/>
+</div>
+</html>