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.