Copyright (C) 2003  Internet Software Consortium.

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

$Id: shared-state.txt,v 1.1 2003/02/12 21:30:54 lidl Exp $

The ISC OpenReg system implements a shared-state mechanism to allow
for any frontend process(es) to share state with the backend (xaction)
process.  This is currently used to store the identity of the
logged in register for each session -- more state is expected to be
shared in future releases of the software.

Format for the feid and sid identifiers:
----------------------------------------

There are two identifiers used by the frontend and the backend for
passing session identifiers back and forth.

The first identifier is generated by the frontend, and is string
of the form 'hostname/ip address/port'.  This string should be be
unique for each frontend process, even when the ip address and port
are shared on different hosts (which would be the case of certain
frame-level load balancing devices, which front-end for a large
number of machines).  This is referred to as the 'feid' (frontend
identifier).

The second identifier is generated by the running backend instance,
and is the start time of the backend, a hyphen, and a simple integer
number.  This identifier is referred to as the 'sid' (session
identifier).

These two identifiers, when combined together, uniquely represent
a client session.

Creation of state:
------------------

When the backend process is started, it has no knowledge of any state.

When a frontend process is started, it sends a startup message to
the backend.   Upon receiving this message, the backend will flush
any saved state for that frontend from its in-memory storage.
After discarding any old state for that frontend and any client
sessions that the frontend might have previously had active, the
backend will create a stub data item for that frontend.

When a client connection is made to a frontend, the first EPP
command that must be issued to the backend is 'login' -- the backend
will assign a sid to the connection, if the login connection is
successful.

Every command sent to the backend on behalf of the client is tagged
with the feid and sid of the client.  The backend uses these
identifiers to locate the stored state for that connection.

When a client connection is terminated by a logout message, the
backend will deallocate the storage for that session.

Maintaining state:
------------------

If a frontend process is stopped, all state about existing client
connections is lost in the frontend.  Additionally, all client
connections are terminated.  When the frontend is restarted,
it sends a startup message to the backend, which causes the backend
to drop all state for that frontend.  In this manner, the shared
state between the frontend and the backend is synchronized.

If a running frontend is shutdown and never restarted, the storage
for the state of that frontend's object in the backend will be lost
until the backend is restarted.  The termination of a frontend that
is never restarted is expected to be a relatively rare event.

If a backend is stopped and restarted, all state on the backend is
lost.  Any current connections between the clients and the frontend
are not disturbed.  These connections will need to be aborted with
an error message when the client issues the next command (except
for a logout command, which can be completed without an error) on
that connection.  The existing connections are effectively orphaned.

If an orphaned client sends a message, the frontend's message to
the backend will contain with the stale feid/sid information for
the connection.  The backend will recognize that this feid is
unknown and create a stub data structure for it.  The backend will
then recognize that the sid is unknown for the given feid, and send
back a reject message to the frontend, which will cause the client
session to be aborted.  In this manner, the state on the backend
will be synchronized with the frontend as each active client on
the frontend will be rejected when the next command is attempted.

New client logins on the the frontend will create state as needed
in the backend.

