copious-transitions
Version:
Framework for working with frameworks
1,007 lines (321 loc) • 22.3 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: TransitionHandling</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: TransitionHandling</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>
<span class="ancestors"><a href="Contractual.html">Contractual</a>.</span>TransitionHandling<span class="signature">()</span><span class="type-signature"></span></h2>
<div class="class-description"><p>Transition handling is a collection of POST method responses designed to provide executive action.
There are just a few methods that guide the process by puting the request through tests supplied by the
session manager, a validator, and a transition processor until a transition finalization method can be called.</p>
<p>A transition may operate in response to a single request, or it might cache salietn data and utimately achieve finalization
after negotiating a second request with the requesting client.</p>
<p>The basic method that runs a transition is <code>transition_handler</code>. And, if a secondary action is required for a transition,
the <code>secondary_transition_handler</code> method will be invoked in response to the appropriate request from the requesting client.</p>
<p>Two other methods are provided by this class, <code>ws_transition</code> and <code>endpoint_transition</code>. These methods work in response to
messages from communication paths other than HTTP communication paths. While the <code>CopiousTransitions</code> sets up an HTTP(s) web
server and handles requests coming to certain types of API paths, the other methods use WebSockets in one case and TCP(tls)
communication in the second case. These methods call upon <code>transition_handler</code> and <code>secondary_transition_handler</code> to do their work.
They will then shape their responses to WS clients or relay clients.</p>
<p>Note that one can imagine a transtion machine implemented explicitly in the application and that a single transition machine instance can
belong to a session. Some applications may implement the actual transition machine. Often, though, the transition machine
is a set of calls out to the DB interface or to the transition engine, which might send data somewhere or publish a message.
The point of these methods is to create a skeleton for the flow of transition processing.</p></div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="TransitionHandling"><span class="type-signature"></span>new TransitionHandling<span class="signature">()</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="contractual_transition_processing.js.html">contractual/transition_processing.js</a>, <a href="contractual_transition_processing.js.html#line30">line 30</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Extends</h3>
<ul>
<li>LocalTObjectCache</li>
</ul>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="endpoint_transition"><span class="type-signature">(async) </span>endpoint_transition<span class="signature">(transition, body)</span><span class="type-signature"> → {Array}</span></h4>
<div class="description">
<p>This method is named <code>endpoint_transition</code> due to its servicing the operations of an endpoint server (as defined in the package
message-relay-server). This method looks for a token on the message (body). If the token is not there, it assumes the
message arriving at the endpoint is in the first phase of transition processing and sends the data on to the transition handler.</p>
<p>If the token is present, the method assumes that the message is targeted to the secondary action.</p>
<p>The branches return the result of the methods they call, and the UserMessageEndpoint instance is written to
send the response back to the relay client (message-relay-server) in an appropriate form using the transtion hanlder results.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>transition</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>body</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="contractual_transition_processing.js.html">contractual/transition_processing.js</a>, <a href="contractual_transition_processing.js.html#line218">line 218</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<ul>
<li>a tupple really, that has: 1) the status code, 2) the JSON response, 3) possibly data or boolean (false for not in use)</li>
</ul>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array</span>
</dd>
</dl>
<h4 class="name" id="secondary_transition_handler"><span class="type-signature">(async) </span>secondary_transition_handler<span class="signature">(body, transmision_headers)</span><span class="type-signature"> → {Array}</span></h4>
<div class="description">
<p>This method progresses a transtion request towards finalization provided that the transition can be identified by its token.
The previously generated data that was not sent to the client will be extracted from the transition object keyed by the token.</p>
<p>Just one check, a match between the object sent in the request from the client and the cached transition object needs to pass.
The match test might be one of a number of possible checks, ranging in in complexity from the check to see is a field is present, to
checking if same name fields of the two objects are equal, to signature verification using elliptic key crypotgraphy, or perhaps more.
The match implementation is part of the application.</p>
<p>Once the match is passed, the secondary transition handler calls up the transition finalization method for the transition machine
operating with respect to the current session.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>body</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>transmision_headers</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="contractual_transition_processing.js.html">contractual/transition_processing.js</a>, <a href="contractual_transition_processing.js.html#line162">line 162</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<ul>
<li>a tupple really, that has: 1) the status code, 2) the JSON response, 3) possibly data or boolean (false for not in use)</li>
</ul>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array</span>
</dd>
</dl>
<h4 class="name" id="transition_handler"><span class="type-signature">(async) </span>transition_handler<span class="signature">(transition, body, transmision_headers)</span><span class="type-signature"> → {Array}</span></h4>
<div class="description">
<p>The transition hanlder is the CopiousTransitions entry point into an application's state transition
implementation. This method supplies the basic framework for stepping the transition request through permission,
acceptance, processing setup, until the state transition can be finalized either in response to the first request or
in response to a secondary request (<code>secondary_action</code>).</p>
<p>The transition handler first calls the session manager's guard. The guard can provide a certain amount of access control
and may also know about the state of the server and the permissibility of certain types of transactions. A failure
to pass the guard yields a reson of unavailability to the requester.</p>
<p>If the guard is passed, the validator checks the trasition body for addmissable data types, etc. In many use case,
the call to the validator is moot. Yet, in some operations the application will prvodide checking methods that the
validator framework can use.</p>
<p>After validation, the transition is examined for feasibility. By feasibility is meant that the state of the server relative to the session
can allow for the transition to a desired state and that the resources required for the transition are available. The check must be
determined by the application. The check can be any degree of complexity from something simple such as accepting the name of
the transition to something quite complicated such as checking that certain machines are attached to the server and that certain
measurement are with desired ranges. What is provided here, is that the transition server will call on the feasibility test provided
by the application after validation and before transition processing and, furthermore, the transition handler will wait (await)
the completion of the feasibility testing.</p>
<p>Requests remaining after they are deemed feasible, can be processed using the session manager's <code>process_transition</code>,
which sets up the data needed for finalization and determines if the transaction will happen in one step or
require a secondary action.</p>
<p>Those transitions that can be done in one step proceed immediately to finalization. The finalization method, provided
by the application, should set the state transition for the session. The method should result in a the transition machine
owned by the session being in an identifiable state. When the session is queried for the state of the machine, the state
of the last finalization should be reported. A query of the state should remain the same with respect to the session
until another state transition is requested.</p>
<p>Those transitions requiring a secondary action before finalization will cache data in preparation for the second action to be done
in response to an ensuing request. The transition handler calls out to the dynamic data producer to produce the data to be cached.
The transition handler will cache the data using the methods provided by LocalTObjectCache; the data is cached
into a map structure with the transition's token as the key. Once the data is cached,
the partial transition object containing data for the client will be sent to the requester along with the parts of the generated data chosen to be sent. Data is sent
in preparation for the secondary action according to a contract of design established for the synchronization of client and server
operations and negotiations.</p>
<p>Given the client comes back with the request for the seconary action, the next handler <code>secondary_transition_handler</code> will
continue the process of progression the transtion to finalization.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>transition</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>the type of transition the client is requesting. See documentation about tagged transisions.</p></td>
</tr>
<tr>
<td class="name"><code>body</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>transmision_headers</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="contractual_transition_processing.js.html">contractual/transition_processing.js</a>, <a href="contractual_transition_processing.js.html#line93">line 93</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<ul>
<li>a tupple really, that has: 1) the status code, 2) the JSON response, 3) possibly data or boolean (false for not in use)</li>
</ul>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array</span>
</dd>
</dl>
<h4 class="name" id="ws_transition"><span class="type-signature">(async) </span>ws_transition<span class="signature">(transition, body)</span><span class="type-signature"> → {Array}</span></h4>
<div class="description">
<p>This method does a very short one step version of transtion processing in response to websocket
messages inbound from the client. This method only check on the feasiblily of the transition and
if it finds it feasible, the transition will be move on to finalization.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>transition</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>body</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="contractual_transition_processing.js.html">contractual/transition_processing.js</a>, <a href="contractual_transition_processing.js.html#line192">line 192</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<ul>
<li>a tupple really, that has: 1) the status code, 2) the JSON response, 3) possibly data or boolean (false for not in use)</li>
</ul>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array</span>
</dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="Contractual.html">Contractual</a></li><li><a href="CopiousTransitions.html">CopiousTransitions</a></li><li><a href="DefaultDB.html">DefaultDB</a></li><li><a href="base.html">base</a></li><li><a href="field_validators.html">field_validators</a></li></ul><h3>Classes</h3><ul><li><a href="Contractual.LocalTObjectCache.html">LocalTObjectCache</a></li><li><a href="Contractual.MimeHandling.html">MimeHandling</a></li><li><a href="Contractual.TransitionHandling.html">TransitionHandling</a></li><li><a href="Contractual.UserHandling.html">UserHandling</a></li><li><a href="CopiousTransitions.CopiousTransitions.html">CopiousTransitions</a></li><li><a href="DefaultDB.CustomizationMethodsByApplication.html">CustomizationMethodsByApplication</a></li><li><a href="DefaultDB.FauxInMemStore.html">FauxInMemStore</a></li><li><a href="DefaultDB.FileMapper.html">FileMapper</a></li><li><a href="DefaultDB.FilesAndRelays.html">FilesAndRelays</a></li><li><a href="DefaultDB.FilesAndRelays_base.html">FilesAndRelays_base</a></li><li><a href="DefaultDB.LocalStaticDB.html">LocalStaticDB</a></li><li><a href="DefaultDB.LocalStorageLifeCycle.html">LocalStorageLifeCycle</a></li><li><a href="DefaultDB.LocalStorageSerialization.html">LocalStorageSerialization</a></li><li><a href="DefaultDB.PageableMemStoreElement.html">PageableMemStoreElement</a></li><li><a href="DefaultDB.PersistenceContracts.html">PersistenceContracts</a></li><li><a href="DefaultDB.RemoteMessaging.html">RemoteMessaging</a></li><li><a href="DefaultDB.StaticDBDefault.html">StaticDBDefault</a></li><li><a href="GeneralUserDBWrapperImpl.html">GeneralUserDBWrapperImpl</a></li><li><a href="SessionTokenManager.html">SessionTokenManager</a></li><li><a href="base.DBClass.html">DBClass</a></li><li><a href="base.EndpointManager.html">EndpointManager</a></li><li><a href="base.GeneralAppLifeCycle.html">GeneralAppLifeCycle</a></li><li><a href="base.GeneralAuth.html">GeneralAuth</a></li><li><a href="base.GeneralBusiness.html">GeneralBusiness</a></li><li><a href="base.GeneralDynamic.html">GeneralDynamic</a></li><li><a href="base.GeneralMiddleWare.html">GeneralMiddleWare</a></li><li><a href="base.GeneralStatic.html">GeneralStatic</a></li><li><a href="base.GeneralTransitionEngImpl.html">GeneralTransitionEngImpl</a></li><li><a href="base.SessionManager.html">SessionManager</a></li><li><a href="base.SessionManager_Lite.html">SessionManager_Lite</a></li><li><a href="base.TaggedTransition.html">TaggedTransition</a></li><li><a href="base.TokenTables.html">TokenTables</a></li><li><a href="base.UserMessageEndpoint.html">UserMessageEndpoint</a></li><li><a href="base.WebSocketManager.html">WebSocketManager</a></li><li><a href="field_validators.DataLookupField.html">DataLookupField</a></li><li><a href="field_validators.EmailField.html">EmailField</a></li><li><a href="field_validators.EmailVerifyField.html">EmailVerifyField</a></li><li><a href="field_validators.FieldTest.html">FieldTest</a></li><li><a href="field_validators.FieldValidatorTools.html">FieldValidatorTools</a></li><li><a href="field_validators.ForeignAuth.html">ForeignAuth</a></li><li><a href="field_validators.GeneralValidator.html">GeneralValidator</a></li><li><a href="field_validators.LengthyAlphabetField.html">LengthyAlphabetField</a></li><li><a href="field_validators.LengthyDigitalField.html">LengthyDigitalField</a></li><li><a href="field_validators.LengthyField.html">LengthyField</a></li><li><a href="field_validators.LengthyStringField.html">LengthyStringField</a></li><li><a href="field_validators.PasswordField.html">PasswordField</a></li><li><a href="field_validators.PasswordVerifyField.html">PasswordVerifyField</a></li><li><a href="field_validators.TypeCheckField.html">TypeCheckField</a></li></ul><h3>Global</h3><ul><li><a href="global.html#generate_password_block">generate_password_block</a></li><li><a href="global.html#load_configuration">load_configuration</a></li><li><a href="global.html#load_parameters">load_parameters</a></li><li><a href="global.html#module_top">module_top</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Tue Oct 31 2023 17:32:59 GMT-0700 (Pacific Daylight Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>