COP Introduction

The VIRGO-COP network protocol enables a VIRGA server to update the global and per-feed state of a VIRGO instance. A VIRGO instance maintains a global state and a per-feed state which are stored persistently on the computer on which VIRGO is running. The currently active VIRGO state is associated with a modification date which indicates the generation of the state. New state may be applied to VIRGO at any time by including the new state with a new modification date in the reply to a VIRGO status message. However, VIRGO will only update its state if the new modification date is strictly greater than the current modification date. New state with a modification date earlier than or equal to the current modification date is ignored by VIRGO.

A good way to look at the state of a VIRGO daemon is that it moves along a timeline. The timeline always starts at 0 and with the factory settings. Each update to the VIRGO state advances the timeline to a new modification date. A state update may only move the timeline forward and not backward. Note however that the VIRGO-COP does offer a mechanism for a VIRGA server to reset the timeline back to 0 before a new state update is applied. This allows a VIRGA server to reset a VIRGO daemon, which may be in an unknown state, back to a well defined state.

Client Identity and Type

Each VIRGO instance is identified with an immutable identifier. This identifier is securely configured on the machine VIRGO runs on during deployment. It can only be changed in the factory by another deployment. It is passed along in every call the VIRGO instance makes to a VIRGO server in an X-CLIENT-ID header.

VIRGO also sends an X-CLIENT-TYPE header which is a combination of the VIRGO application name and the platform on which VIRGO is running. Currently the following client types are supported:

X-CLIENT-TYPE Platform
Virgo-macOS macOS
Virgo-Linux Linux

VIRGO Configuration

The configuration of a VIRGO daemon can be broken down into two subsets:

The current VIRGO configuration is associated with a modification date which is initially 0 and which is advanced to a new date every time the state is updated. All state information including the modification date is stored persistently by the VIRGO daemon and is guaranteed to survive daemon shutdowns and restarts.

Note: A description of semantic versioning is available here: http://semver.org

Data Types

The following table specifies the data types that may appear in a COP request or response:

COP Type JSON Type Description
Bool Bool true or false
Int Int64 64-bit wide signed integer
Float Float64 Double precision IEEE 754 floating point
String UnicodeString Unicode compliant string encoded in UTF-8
URL UnicodeString URL compliant with standards RFC 1808, RFC 1738, and RFC 2732
EpochTime Int64 Milliseconds since January 1, 1970 at 00:00:00 GMT (GMT == UTC)
Milliseconds Int64 Time interval expressed in milliseconds
Version UnicodeString Semantic version (e.g. “10.2.4”)

A COP type may be optional which is indicated by a ‘?’ (question mark) after the type name. An optional property may be left out in a request and may or may not appear in a response. Non-optional properties are always required in a request and are guaranteed to appear in a response.

See Also