Spec:connection

Connection stack
The connection module shall use a connection stack to separates the various elements of the implementation.

Module layer
The module layer shall be implemented in main.cpp and init.cpp files.

Initialization

 * Socket initialization : The module shall initialize the socket subsystem (Windows only).
 * Class registration : The module layer shall manage the registration of the connection class.
 * Module globals : The module layer shall publish the connection module global variables, including.
 * security_level : The module shall publish a security level control global variable as an enumeration with values NONE, LOW, STANDARD, HIGH, EXTREME, PARANOID.
 * security_lockout : The module shall publish a security lockout time global variable in seconds.

Client/Server layer
The client/server layer shall be implemented in the client and server classes.

The client/server class shall be one of three possible states at any time:
 * STARTING : The connection is not yet fully set up and ready
 * READY : The connection is ready to accept incoming messages (server) or send outgoing messages (client).
 * SHUTDOWN : The connection is shutting down and no longer handling messages.

Local interface
The local interfaces for the client/server classes shall include the following:
 * accept_tcp : interface to wait for and accept a TCP connection
 * accept_udp : interface to wait for incoming UDP message
 * get_type : interface to determine what type of connection is active (stream or datagram)
 * get_maxbacklog : interface to determine how much incoming connection backlog is allowed for TCP listen process.
 * process_msg : interface to dispatch an incoming message to the appropriate handler

Remote interface
The remote class shall encapsulate the following data items
 * Client : Each client shall have a server structure to track the state and thread for the remote socket.
 * Server : Each server shall have a client structure to track the state and thread for the remote socket.

The following interfaces shall be supported
 * get_client/get_server : interface to obtain local client/server associated with this interface
 * set_proc : interface to allow the local interface to control the remote interface's thread process.
 * get_proc : interface to allow the local interface to identify the remote interface's thread process.

Native
The native class shall be a GridLAB-D module class.

The native class shall implement all the event handlers for the GridLAB-D core (i.e., init, precommit, presync, sync, postsync, commit, prenotify, postnotify, plc, finalize, and term).

The native class shall implement the link pseudo-property.

The native class shall publish the following properties:
 * mode : determine which mode of operation (CLIENT or SERVER).
 * transport : determine which transport is used (TCP or UDP).

The native class shall maintain the variable maps for each event handler.

XML
The xml class shall be derived from the native class.

The xml class shall publish the following variables:
 * encoding : specifies UTF8 (default) or UTF16 encoding method to use
 * version : specifies the version of XML (i.e., 1.0) to use
 * schema : specifis the URL for the XML schema (xsd) to use
 * stylesheet : specifies the XML stylesheet (xsl) to use

JSON
The json class shall be derived from the natice class.

The json class shall publish the following variables:
 * version : specifies the JSON version to use

Cache layer
The cache shall be implemented as single cache for all variable maps associated with all events.

The cache shall preserve a single copy of all messages associated with any particular link item.

The cache shall implement separate read and write operations for variable maps.

The cache shall provide an interface to set the message translation (e.g., native<->xml, native<->json).

The cache shall use a hash table to identify entries using object id, property address, and remote name.

Each variable map shall use a separate cache entry list to enumerate the cache entries that must be updated.

The cache class shall provide the following interfaces:
 * set_size : establish the size of the cache list
 * get_size : determine the size of the cache list
 * write : write a variable to the cache using a translator
 * read : read a variable from the cache using a translator

The cacheitem class shall provide the following interfaces:
 * constructor : construct a new cache item based on an object/property/remote-name tuple
 * init : initialize the cache item list
 * grow : enlarge the cache after a hash collision has been encountered.
 * get_id : obtain the hash of an object/property/remote-name tuple modulo the hash size
 * get_item : get a cache item based on the hash id
 * get_object : get the object associated with a cache item
 * get_property : get the property associated with a cache item
 * get_remote : get the remote-name associated with a cache item
 * read : copy from the cache to the variable associated with it
 * write : copy to the cache from the variable associated with it
 * set_translator : set the translator to use with the cache item (e.g., XML, JSON)

Transport layer
Verify that engine protocol supports all the needed exchanges. It looks like it might be too oriented toward copying data and not enough to more general needs of connection module.

The transport layer shall be implemented using independent receive and transmit threads to asynchronously post incoming traffic to the cache and transmit outgoing traffic in the cache.

TCP
The tcp class shall implement message transport using the TCP protocol using the engine protocol.

UDP
The udp class shall implement message transport using the UDP protocol using the engine protocol.

Payload format
The message format shall be


 * "G" "L" version[1] " " size[4] message[size]


 * where the version is currently "0", the size is a network short, and the message is in clear text.

Two types of messages shall be supported.

Cache setup messages shall be formatted as


 * MAP id[?] "=" object_id[?] " " property_addr[?] " " remote_name[?] " "
 * Shall be used to provide mapping information to the remote app.

Cache copy message shall be formatted as:


 * id[?] "=" value[?]
 * where id is the cache mapping id, or one of the follow special values
 * CONT : The value provided is the next sync timestamp but should not be used to drive GridLAB-D's clock.
 * NEXT : The value provided is the next sync timestamp and should be used to drive GridLAB-D's clock.
 * ERROR : An error has been encountered and the value is a string indicating the nature of the error.
 * RETRY : Indicates that the remote app would like GridLAB-D to iterate without advancing the clock.
 * NEVER : Indicates that the remote app would like GridLAB-D to not use the default sync time.

Security level
The following security levels shall be supported:
 * NONE : access controls shall not be enforced
 * LOW : access to everything shall be permitted unless explicitly forbidden using forbid link.
 * STANDARD : access shall conform to PT_ACCESS control unless explicitly forbidden using forbid link.
 * HIGH : access shall conform to PT_ACCESS control when explicitly permitted using ''allow' link.
 * EXTREME : access shall not be permitted to anything unless explicitly permitted using allow link.
 * PARANOID : same as EXTREME but violations result in a security lockout (see Security lockout)

Security lockout
Violations of security access when security level is PARANOID shall result in a security access lockout delay, which shall last the number of seconds specified the security_lockout global variable.

Deltamode
When run_realtime=1 delta mode shall maintain clock synchronization at subsecond intervals. Delta mode shall not be supported for run_realtime>1.

The connection module shall support delta mode for all active connections. When the delta_timestep property of the connection object is non-zero, then delta mode is active and the variable map "delta" shall be processed at the interval indicated by delta_timestep.

Clock drift
The core shall support clock drift when run_realtime=1.0. The clock drift rate shall be computed as follows:


 * clock_drift_rate (ms/s) = clock_alpha (ms/s^2) &times; clock_skew (s)

where clock_alpha is set by the user and is by default 10 ms/s^2, and clock_skew is the difference between the system clock and the simulation clock (in seconds)


 * clock_skew = system_clock - clock

The following global variables shall be supported


 * clock_drift_rate : The rate in ms/s at which the clock is drifting (read-only, updated every second).
 * clock_alpha : The proportionality constant used to calculate the clock_drift_rate (default is 10 ms/s^2).
 * clock_skew : The difference in ms between the system clock and simulation clock (readonly, updated every second)
 * system_clock : The current system clock in seconds of epoch (updated every second).

Synchronization time
Assess this section in view of the following questions:
 * Is this overly constraining remote apps that don't understand sync process?
 * Will this allow complete connection to remote apps that require sync process too?
 * Is this going to work with minimum_timestep?
 * The use cases ought to be helpful in answering these questions.

By default all connection objects shall use a 1 second synchronization.

In the absence of a synchronization time from the remote application the connection:timestep shall be used.

The connection timestep shall be specified in seconds with a resolution of 1 nanosecond for compability with deltamode time resolution.

When the remote application needs to affect the next synchronization time, the time shall be provided in either absolute seconds of the epoch (UTC), relative seconds or the extended ISO format, i.e.,


 * NEXT ssssssssss[.ssssss]
 * NEXT +ssssssssss[.sssssss]
 * NEXT YYYY-MM-DD hh:mm:ss[.ssssss] ZZZ : where if the timezone ZZZ is omitted, local time is assumed.

The following synchronization special conditions shall be supported (in which case the time is not provided):


 * NEVER : Indicates no synchronization time is available
 * ERROR : Indicates the remote application has encountered a fatal error and cannot continue
 * RETRY : Indicates the remote application would like to iterate the current time once more

The following synchronization shall be used for sync times that are considered only if another sync time is driving the simulation forward. Otherwise the sync time shall be treated as NEVER.


 * COND sssssssss[.ssssss]
 * COND +ssssssssss[.sssssss]
 * COND YYYY-MM-DD hh:mm:ss[.ssssss] ZZZ : where if the timezone ZZZ is omitted, local time is assumed.

Version
The connection module is proposed for. Its development is tracked under [/797 Ticket 797].