Example OpenCLAWS messaging sketch

2013-03-04 13:17

Example OpenCLAWS messaging sketch

User initiates a 'add new host' request from the frontend client, fills in whatever information the frontend client requests. The frontend client constructs an event to be sent through the system.

<claws:event txid="000000-0000-0000-000000000000">
    <claws:source>Web Client</claws:source>
    <claws:identity>Alice</claws:identity>
    <host:add-host>
        <host:hostname>Alice-PC</host:hostname>
        <host:mac-addr name="ethernet">00:00:00:00:00:00</host:mac-addr>
        <host:mac-addr name="wifi">00:00:00:00:00:01</host:mac-addr>
        <wireless:roaming name="wifi"/>
        <lan:vlan name="ethernet">guest-network</lan:vlan>
        <dns:auto-assign-fqdn/>
        <host:operating-system>Windows 7</host:operating-system>
        <host:asset-tag>000001</host:asset-tag>
    </host:add-host>
</claws:event>

The Claws central server receives this message, ensures the identity and source information are authorized, but otherwise performs no additional checking. Then it records the txid information, along with additional event processing state before broadcasting a modified event to connected modules. (NOTE: possible subscription processing here, to avoid sending events to modules that are uninterested in them).

<claws:event txid="000000-0000-0000-000000000000"
             status="provisional"
             timestamp="2013-03-07 13:45:27.554620">
    <claws:source>Web Client</claws:source>
    <claws:identity>Alice</claws:identity>
    <host:add-host>
        <host:hostname>Alice-PC</host:hostname>
        <host:mac-addr name="ethernet">00:00:00:00:00:00</host:mac-addr>
        <host:mac-addr name="wifi">00:00:00:00:00:01</host:mac-addr>
        <wireless:roaming name="wifi"/>
        <lan:vlan name="ethernet">guest-network</lan:vlan>
        <dns:auto-assign-fqdn/>
        <host:operating-system>Windows 7</host:operating-system>
        <host:asset-tag>000001</host:asset-tag>
    </host:add-host>
</claws:event>

Each module that receives this event will note the provisional status, which indicates that it may send back an updating message to include additional information before the final event is broadcast. This acts as a two-phase commit-like operation. (NOTE: Issue of timeouts needs to be addressed, relying on receiving an update message, even if empty, from all modules which received the broadcast is not going to be 100% reliable.)

On the assumption there are two modules which will respond, a DNS management module and a combined lan/wlan/dhcp management module (for simplicity's sake in this example, likely not the case in a sufficiently interesting network), the module's update messages might look like this

<claws:event-update txid="000000-0000-0000-000000000000">
    <claws:source>DNS Management Module</claws:source>
    <claws:module-version>0.1.0</claws:module-version>
    <host:add-host update-action="append">
        <dns:fqdn>alice-pc.roamer.example.com</dns:fqdn>
    </host:add-host>
    <host:add-host update-action="remove">
        <dns:auto-assign-fqdn/>
    </host:add-host>
</claws:event>

<claws:event-update txid="000000-0000-0000-000000000000">
    <claws:source>Address and Network Management Module</claws:source>
    <claws:module-version>0.1.0</claws:module-version>
    <host:add-host update-action="append">
        <lan:network name="ethernet">192.168.50.0</lan:network>
        <lan:network name="ethernet">2000::/3</lan:network>
        <lan:address name="ethernet">192.168.50.4</lan:address>
        <lan:address name="ethernet">2001::58</lan:address>
        <dhcp:custom-option number="252">\n</dhcp:custom-option>
    </host:add-host>
</claws:event>

At this point, the central claws server will combine the updated event data and send out a final event, which will trigger any modules to perform the necessary actions to respond to the event (e.g. update DNS records, provision DHCP servers and firewalls)

<claws:event txid="000000-0000-0000-000000000000"
             status="final"
             timestamp="2013-03-07 13:45:27.554620">
    <claws:source>Web Client</claws:source>
    <claws:identity>Alice</claws:identity>
    <host:add-host>
        <host:hostname>Alice-PC</host:hostname>
        <host:mac-addr name="ethernet">00:00:00:00:00:00</host:mac-addr>
        <host:mac-addr name="wifi">00:00:00:00:00:01</host:mac-addr>
        <wireless:roaming name="wifi"/>
        <lan:vlan name="ethernet">guest-network</lan:vlan>
        <dhcp:custom-option number="252">\n</dhcp:custom-option>
        <host:operating-system>Windows 7</host:operating-system>
        <host:asset-tag>000001</host:asset-tag>
        <dns:fqdn>alice-pc.roamer.example.com</dns:fqdn>
        <lan:network name="ethernet">192.168.50.0</lan:network>
        <lan:network name="ethernet">2000::/3</lan:network>
        <lan:address name="ethernet">192.168.50.4</lan:address>
        <lan:address name="ethernet">2001::58</lan:address>
    </host:add-host>
</claws:event>

At this point, the modules will have executed the necessary steps to perform their functions in response to the final event from the claws central server. In order to be able to provide useful progress and completion feedback, modules should emit events that contain a correlating txid to the 'primary' event to the frontend clients can provide friendly user feedback.

<claws:event txid="000000-0000-0000-000000000001" status="final">
    <claws:source>DNS Management Module</claws:source>
    <claws:module-version>0.1.0</claws:module-version>
    <claws:correlation-id>000000-0000-0000-000000000000</claws:correlation-id>
    <claws:progress-percent>0</claws:progress-percent>
</claws:event>

<claws:event txid="000000-0000-0000-000000000001" status="final">
    <claws:source>DNS Management Module</claws:source>
    <claws:module-version>0.1.0</claws:module-version>
    <claws:correlation-id>000000-0000-0000-000000000000</claws:correlation-id>
    <claws:progress-percent>33</claws:progress-percent>
    <claws:progress-message>Adding FQDN forward and reverse records to
    zone.</claws:progress-message>
</claws:event>

<claws:event txid="000000-0000-0000-000000000001" status="final">
    <claws:source>DNS Management Module</claws:source>
    <claws:module-version>0.1.0</claws:module-version>
    <claws:correlation-id>000000-0000-0000-000000000000</claws:correlation-id>
    <claws:progress-percent>66</claws:progress-percent>
    <claws:progress-message>Reloading zone</claws:progress-message>
</claws:event>

<claws:event txid="000000-0000-0000-000000000001" status="final">
    <claws:source>DNS Management Module</claws:source>
    <claws:module-version>0.1.0</claws:module-version>
    <claws:correlation-id>000000-0000-0000-000000000000</claws:correlation-id>
    <claws:progress-percent>100</claws:progress-percent>
    <claws:progress-message>Provisioning DNS server complete.</claws:progress-message>
</claws:event>

These messages would flow through the central claws server, and be give timestamps, but would not be broadcast as provisional messages, it is likely desirable that the messages would be sent with an addressing key of the related transaction so only the frontend client that initiated the request would receive them.