github.com/jbking/gohan@v0.0.0-20151217002006-b41ccf1c2a96/docs/source/sync.rst (about)

     1  =================
     2  Sync with backend
     3  =================
     4  
     5  Gohan stores an event log recording create, update and delete database operations.
     6  This is done in the database transaction, so we can assume that
     7  this event log data is consistent with the resource data.
     8  
     9  The event log data contains the following information. (see schema in gohan.json)
    10  
    11  - id -- an unique ID of the event
    12  - type -- the type of the event
    13  - path -- the path of the resource related to the event
    14  - timestamp -- the time at which the event occurred
    15  - version -- the version of the resource after this event occurred
    16  - body -- the contents of the resource after this event occurred
    17  
    18  The Gohan server will select one master node using the etcd backend CAS API.
    19  Only the master node will then poll the event log table, pushing to the backend.
    20  
    21  We may support mysql binlog api for better performance in future.
    22  
    23  .. _subsection-state-update:
    24  
    25  State updates
    26  -------------
    27  
    28  Gohan will keep track of the state version of any resource associated to
    29  a schema with metadata containing the key ``state_versioning`` set to
    30  ``true``. In such a case Gohan will remember the config version and
    31  the state version of the resource. During creation the config version of
    32  such a resource will be set to ``1``. On delete and update the version is
    33  bumped by one. The state version is ``0`` originally and later read from
    34  the sync backend and updated asynchronously. Both the versions are returned
    35  in GET requests, together with additional information about the state.
    36  
    37  For example say a simplistic resource with the following schema is created:
    38  
    39  .. code-block:: yaml
    40  
    41      - description: Just a named object
    42        id: named_object
    43        parent: ""
    44        metadata:
    45          state_versioning: true
    46        singular: named_object
    47        plural: named_object
    48        prefix: /v1.0
    49        schema:
    50          properties:
    51            name:
    52              default: ""
    53              permission:
    54              - create
    55              - update
    56              title: Name
    57              type: string
    58              unique: false
    59            id:
    60              permission:
    61              - create
    62              title: ID
    63              type: string
    64              format: uuid
    65          properties_order:
    66          - id
    67          - name
    68          required:
    69          - name
    70          type: object
    71        title: Named Object
    72  
    73  and the ``name`` is set to ``Alice``. Then Gohan, through the standard event sync,
    74  writes the following JSON object to the backend under the key
    75  ``config/v1.0/named_object/someGeneratedUuid``:
    76  
    77  .. code-block:: javascript
    78  
    79      {
    80        "body": {
    81          "id": "someGeneratedUuid",
    82          "name": "Alice"
    83        },
    84        "version": 1
    85      }
    86  
    87  A worker program might now read this information, create a corresponding
    88  southbound resource and write the following to the backend under the key
    89  ``state/v1.0/named_object/someGeneratedUuid``:
    90  
    91  .. code-block:: javascript
    92  
    93      {
    94        "version": 1,
    95        "error": "",
    96        "state": "Alice exists"
    97      }
    98  
    99  Gohan will read this information and update the database accordingly.
   100  
   101  Any state updates made when the state version already equals the config version
   102  will be ignored.
   103  
   104  Monitoring updates
   105  ------------------
   106  
   107  After a resource has been created in the southbound, one might monitor its
   108  status. This is done using a very similar approach to status updates.
   109  Monitoring updates the ``monitoring`` field in the database, which is returned
   110  together with the rest of the state.
   111  
   112  A continuation of the above example follows. After the resource has been created
   113  in the southbound a worker program might monitor its status and then write
   114  the result of this monitoring under the key
   115  ``monitoring/v1.0/named_object/someGeneratedUuid`` as the following JSON:
   116  
   117  .. code-block:: javascript
   118  
   119      {
   120        "monitoring": "Alice is well"
   121      }
   122  
   123  Gohan will read this information and update the database accordingly.
   124  
   125  Any monitoring updates made when the state version does not yet equal
   126  the config version will be ignored.