{"action":"created","comment":{"url":"https://api.github.com/repos/gravity-platform/doc/pulls/comments/39498886","id":39498886,"diff_hunk":"@@ -0,0 +1,286 @@\n+---\n+title: Events\n+layout: default\n+top_nav: api\n+---\n+\n+# Events\n+\n+Graviton supports an event based subscription feature. With this, it is possible for `worker agents` so subscribe\n+on certain events that happen. At the moment, this is limited to data changing events (`PUT`, `POST`, `DELETE`). \n+\n+This allows a `worker` to be notified on any data changes that happen - a worker can flexibly subscribe on whatever it is\n+interested.\n+\n+If a `worker` is subscribed on a certain event, an `EventStatus` resource is created that allows a `worker` to update\n+its progress. This again makes it possible for interested parties (like GUI clients) to follow up on the status of certain\n+actions.\n+\n+The interface between Graviton and the `worker` is a messaged based queue supporting the [AMQP protocol](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol),\n+ we use [RabbitMQ](https://www.rabbitmq.com/). AMQP is widely adopted and bindings exists in virtually any environment,\n+ making it possible to write a `worker` in any language that possesses those bindings and a HTTP client.\n+\n+## When this should be used\n+\n+This feature is intended for any features that require \"background work\", like sending an email when a certain record\n+has been created. One could write an agent that generates a PDF from the user input (subscribing on the relevant events),\n+then POSTing the PDF into the `/file` service.\n+\n+The advantages on using this approach:\n+\n+* It allows to implement additional (maybe client specific) logic without touching the core product\n+* As workers can be in any language, it gives more people the possibility to write this logic.\n+* The async'esque design with issuing a `EventStatus` object as a HTTP resource allows clients and workers to deal more easily with connection interruptions or crashes of different components.\n+\n+## Detailed information\n+\n+### Writing a worker\n+\n+The typical workflow for a worker is as follows:\n+\n+* The worker registers itself on the service `/event/worker/`, `PUT`ing his ID and subscription(s)\n+* The worker connects to the message queue (the same as Graviton), binds to the topic exchange `graviton`.\n+* The worker waits for incoming messages indefinitely.\n+* Now, whenever a data change event happens to which the worker is subscribed, it will receive a message on the queue.\n+* If the worker receives a message, it must be JSON decoded first.\n+* Then, the worker needs to set it's status to `working` (by `PUT`ing a new version of the `EventStatus` object).\n+* The worker does his work\n+* The worker sets his status to `done` (again, by `PUT`ing a new version of the `EventStatus` object).\n+\n+<div class=\"alert alert-info\" markdown=\"1\">\n+**Update your status immediately!**<br />","path":"source/_pages/api/event.md","position":51,"original_position":51,"commit_id":"12db499258ea4e00c3c430feb182990ba26bb220","original_commit_id":"12db499258ea4e00c3c430feb182990ba26bb220","user":{"login":"hairmare","id":116588,"avatar_url":"https://avatars.githubusercontent.com/u/116588?v=3","gravatar_id":"","url":"https://api.github.com/users/hairmare","html_url":"https://github.com/hairmare","followers_url":"https://api.github.com/users/hairmare/followers","following_url":"https://api.github.com/users/hairmare/following{/other_user}","gists_url":"https://api.github.com/users/hairmare/gists{/gist_id}","starred_url":"https://api.github.com/users/hairmare/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hairmare/subscriptions","organizations_url":"https://api.github.com/users/hairmare/orgs","repos_url":"https://api.github.com/users/hairmare/repos","events_url":"https://api.github.com/users/hairmare/events{/privacy}","received_events_url":"https://api.github.com/users/hairmare/received_events","type":"User","site_admin":false},"body":"Needs a line of whitespace before and after div for sculpin to parse it as mardown afaik.","created_at":"2015-09-15T11:21:02Z","updated_at":"2015-09-15T11:21:02Z","html_url":"https://github.com/gravity-platform/doc/pull/7#discussion_r39498886","pull_request_url":"https://api.github.com/repos/gravity-platform/doc/pulls/7","_links":{"self":{"href":"https://api.github.com/repos/gravity-platform/doc/pulls/comments/39498886"},"html":{"href":"https://github.com/gravity-platform/doc/pull/7#discussion_r39498886"},"pull_request":{"href":"https://api.github.com/repos/gravity-platform/doc/pulls/7"}}},"pull_request":{"url":"https://api.github.com/repos/gravity-platform/doc/pulls/7","id":45027745,"html_url":"https://github.com/gravity-platform/doc/pull/7","diff_url":"https://github.com/gravity-platform/doc/pull/7.diff","patch_url":"https://github.com/gravity-platform/doc/pull/7.patch","issue_url":"https://api.github.com/repos/gravity-platform/doc/issues/7","number":7,"state":"open","locked":false,"title":"event doc","user":{"login":"narcoticfresh","id":245441,"avatar_url":"https://avatars.githubusercontent.com/u/245441?v=3","gravatar_id":"","url":"https://api.github.com/users/narcoticfresh","html_url":"https://github.com/narcoticfresh","followers_url":"https://api.github.com/users/narcoticfresh/followers","following_url":"https://api.github.com/users/narcoticfresh/following{/other_user}","gists_url":"https://api.github.com/users/narcoticfresh/gists{/gist_id}","starred_url":"https://api.github.com/users/narcoticfresh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/narcoticfresh/subscriptions","organizations_url":"https://api.github.com/users/narcoticfresh/orgs","repos_url":"https://api.github.com/users/narcoticfresh/repos","events_url":"https://api.github.com/users/narcoticfresh/events{/privacy}","received_events_url":"https://api.github.com/users/narcoticfresh/received_events","type":"User","site_admin":false},"body":"as requested 'a ton of documentation' for the graviton event feature ;-)\r\nalso includes a dep bump.. what can it hurt?","created_at":"2015-09-15T09:38:30Z","updated_at":"2015-09-15T11:21:02Z","closed_at":null,"merged_at":null,"merge_commit_sha":"c1d8fb98123b4c6928c6f506bcdb4c39f519be3f","assignee":{"login":"hairmare","id":116588,"avatar_url":"https://avatars.githubusercontent.com/u/116588?v=3","gravatar_id":"","url":"https://api.github.com/users/hairmare","html_url":"https://github.com/hairmare","followers_url":"https://api.github.com/users/hairmare/followers","following_url":"https://api.github.com/users/hairmare/following{/other_user}","gists_url":"https://api.github.com/users/hairmare/gists{/gist_id}","starred_url":"https://api.github.com/users/hairmare/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hairmare/subscriptions","organizations_url":"https://api.github.com/users/hairmare/orgs","repos_url":"https://api.github.com/users/hairmare/repos","events_url":"https://api.github.com/users/hairmare/events{/privacy}","received_events_url":"https://api.github.com/users/hairmare/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/gravity-platform/doc/pulls/7/commits","review_comments_url":"https://api.github.com/repos/gravity-platform/doc/pulls/7/comments","review_comment_url":"https://api.github.com/repos/gravity-platform/doc/pulls/comments{/number}","comments_url":"https://api.github.com/repos/gravity-platform/doc/issues/7/comments","statuses_url":"https://api.github.com/repos/gravity-platform/doc/statuses/12db499258ea4e00c3c430feb182990ba26bb220","head":{"label":"gravity-platform:feature/event-doc","ref":"feature/event-doc","sha":"12db499258ea4e00c3c430feb182990ba26bb220","user":{"login":"gravity-platform","id":5641107,"avatar_url":"https://avatars.githubusercontent.com/u/5641107?v=3","gravatar_id":"","url":"https://api.github.com/users/gravity-platform","html_url":"https://github.com/gravity-platform","followers_url":"https://api.github.com/users/gravity-platform/followers","following_url":"https://api.github.com/users/gravity-platform/following{/other_user}","gists_url":"https://api.github.com/users/gravity-platform/gists{/gist_id}","starred_url":"https://api.github.com/users/gravity-platform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gravity-platform/subscriptions","organizations_url":"https://api.github.com/users/gravity-platform/orgs","repos_url":"https://api.github.com/users/gravity-platform/repos","events_url":"https://api.github.com/users/gravity-platform/events{/privacy}","received_events_url":"https://api.github.com/users/gravity-platform/received_events","type":"Organization","site_admin":false},"repo":{"id":13422666,"name":"doc","full_name":"gravity-platform/doc","owner":{"login":"gravity-platform","id":5641107,"avatar_url":"https://avatars.githubusercontent.com/u/5641107?v=3","gravatar_id":"","url":"https://api.github.com/users/gravity-platform","html_url":"https://github.com/gravity-platform","followers_url":"https://api.github.com/users/gravity-platform/followers","following_url":"https://api.github.com/users/gravity-platform/following{/other_user}","gists_url":"https://api.github.com/users/gravity-platform/gists{/gist_id}","starred_url":"https://api.github.com/users/gravity-platform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gravity-platform/subscriptions","organizations_url":"https://api.github.com/users/gravity-platform/orgs","repos_url":"https://api.github.com/users/gravity-platform/repos","events_url":"https://api.github.com/users/gravity-platform/events{/privacy}","received_events_url":"https://api.github.com/users/gravity-platform/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gravity-platform/doc","description":"","fork":false,"url":"https://api.github.com/repos/gravity-platform/doc","forks_url":"https://api.github.com/repos/gravity-platform/doc/forks","keys_url":"https://api.github.com/repos/gravity-platform/doc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gravity-platform/doc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gravity-platform/doc/teams","hooks_url":"https://api.github.com/repos/gravity-platform/doc/hooks","issue_events_url":"https://api.github.com/repos/gravity-platform/doc/issues/events{/number}","events_url":"https://api.github.com/repos/gravity-platform/doc/events","assignees_url":"https://api.github.com/repos/gravity-platform/doc/assignees{/user}","branches_url":"https://api.github.com/repos/gravity-platform/doc/branches{/branch}","tags_url":"https://api.github.com/repos/gravity-platform/doc/tags","blobs_url":"https://api.github.com/repos/gravity-platform/doc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gravity-platform/doc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gravity-platform/doc/git/refs{/sha}","trees_url":"https://api.github.com/repos/gravity-platform/doc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gravity-platform/doc/statuses/{sha}","languages_url":"https://api.github.com/repos/gravity-platform/doc/languages","stargazers_url":"https://api.github.com/repos/gravity-platform/doc/stargazers","contributors_url":"https://api.github.com/repos/gravity-platform/doc/contributors","subscribers_url":"https://api.github.com/repos/gravity-platform/doc/subscribers","subscription_url":"https://api.github.com/repos/gravity-platform/doc/subscription","commits_url":"https://api.github.com/repos/gravity-platform/doc/commits{/sha}","git_commits_url":"https://api.github.com/repos/gravity-platform/doc/git/commits{/sha}","comments_url":"https://api.github.com/repos/gravity-platform/doc/comments{/number}","issue_comment_url":"https://api.github.com/repos/gravity-platform/doc/issues/comments{/number}","contents_url":"https://api.github.com/repos/gravity-platform/doc/contents/{+path}","compare_url":"https://api.github.com/repos/gravity-platform/doc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gravity-platform/doc/merges","archive_url":"https://api.github.com/repos/gravity-platform/doc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gravity-platform/doc/downloads","issues_url":"https://api.github.com/repos/gravity-platform/doc/issues{/number}","pulls_url":"https://api.github.com/repos/gravity-platform/doc/pulls{/number}","milestones_url":"https://api.github.com/repos/gravity-platform/doc/milestones{/number}","notifications_url":"https://api.github.com/repos/gravity-platform/doc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gravity-platform/doc/labels{/name}","releases_url":"https://api.github.com/repos/gravity-platform/doc/releases{/id}","created_at":"2013-10-08T18:58:52Z","updated_at":"2015-08-07T13:01:41Z","pushed_at":"2015-09-15T09:38:30Z","git_url":"git://github.com/gravity-platform/doc.git","ssh_url":"git@github.com:gravity-platform/doc.git","clone_url":"https://github.com/gravity-platform/doc.git","svn_url":"https://github.com/gravity-platform/doc","homepage":"https://gravity-platform-docs.nova.scapp.io/","size":676,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"develop"}},"base":{"label":"gravity-platform:develop","ref":"develop","sha":"2bf24635a18f82f62ac0a9310618dbc71610a4c9","user":{"login":"gravity-platform","id":5641107,"avatar_url":"https://avatars.githubusercontent.com/u/5641107?v=3","gravatar_id":"","url":"https://api.github.com/users/gravity-platform","html_url":"https://github.com/gravity-platform","followers_url":"https://api.github.com/users/gravity-platform/followers","following_url":"https://api.github.com/users/gravity-platform/following{/other_user}","gists_url":"https://api.github.com/users/gravity-platform/gists{/gist_id}","starred_url":"https://api.github.com/users/gravity-platform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gravity-platform/subscriptions","organizations_url":"https://api.github.com/users/gravity-platform/orgs","repos_url":"https://api.github.com/users/gravity-platform/repos","events_url":"https://api.github.com/users/gravity-platform/events{/privacy}","received_events_url":"https://api.github.com/users/gravity-platform/received_events","type":"Organization","site_admin":false},"repo":{"id":13422666,"name":"doc","full_name":"gravity-platform/doc","owner":{"login":"gravity-platform","id":5641107,"avatar_url":"https://avatars.githubusercontent.com/u/5641107?v=3","gravatar_id":"","url":"https://api.github.com/users/gravity-platform","html_url":"https://github.com/gravity-platform","followers_url":"https://api.github.com/users/gravity-platform/followers","following_url":"https://api.github.com/users/gravity-platform/following{/other_user}","gists_url":"https://api.github.com/users/gravity-platform/gists{/gist_id}","starred_url":"https://api.github.com/users/gravity-platform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gravity-platform/subscriptions","organizations_url":"https://api.github.com/users/gravity-platform/orgs","repos_url":"https://api.github.com/users/gravity-platform/repos","events_url":"https://api.github.com/users/gravity-platform/events{/privacy}","received_events_url":"https://api.github.com/users/gravity-platform/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gravity-platform/doc","description":"","fork":false,"url":"https://api.github.com/repos/gravity-platform/doc","forks_url":"https://api.github.com/repos/gravity-platform/doc/forks","keys_url":"https://api.github.com/repos/gravity-platform/doc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gravity-platform/doc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gravity-platform/doc/teams","hooks_url":"https://api.github.com/repos/gravity-platform/doc/hooks","issue_events_url":"https://api.github.com/repos/gravity-platform/doc/issues/events{/number}","events_url":"https://api.github.com/repos/gravity-platform/doc/events","assignees_url":"https://api.github.com/repos/gravity-platform/doc/assignees{/user}","branches_url":"https://api.github.com/repos/gravity-platform/doc/branches{/branch}","tags_url":"https://api.github.com/repos/gravity-platform/doc/tags","blobs_url":"https://api.github.com/repos/gravity-platform/doc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gravity-platform/doc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gravity-platform/doc/git/refs{/sha}","trees_url":"https://api.github.com/repos/gravity-platform/doc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gravity-platform/doc/statuses/{sha}","languages_url":"https://api.github.com/repos/gravity-platform/doc/languages","stargazers_url":"https://api.github.com/repos/gravity-platform/doc/stargazers","contributors_url":"https://api.github.com/repos/gravity-platform/doc/contributors","subscribers_url":"https://api.github.com/repos/gravity-platform/doc/subscribers","subscription_url":"https://api.github.com/repos/gravity-platform/doc/subscription","commits_url":"https://api.github.com/repos/gravity-platform/doc/commits{/sha}","git_commits_url":"https://api.github.com/repos/gravity-platform/doc/git/commits{/sha}","comments_url":"https://api.github.com/repos/gravity-platform/doc/comments{/number}","issue_comment_url":"https://api.github.com/repos/gravity-platform/doc/issues/comments{/number}","contents_url":"https://api.github.com/repos/gravity-platform/doc/contents/{+path}","compare_url":"https://api.github.com/repos/gravity-platform/doc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gravity-platform/doc/merges","archive_url":"https://api.github.com/repos/gravity-platform/doc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gravity-platform/doc/downloads","issues_url":"https://api.github.com/repos/gravity-platform/doc/issues{/number}","pulls_url":"https://api.github.com/repos/gravity-platform/doc/pulls{/number}","milestones_url":"https://api.github.com/repos/gravity-platform/doc/milestones{/number}","notifications_url":"https://api.github.com/repos/gravity-platform/doc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gravity-platform/doc/labels{/name}","releases_url":"https://api.github.com/repos/gravity-platform/doc/releases{/id}","created_at":"2013-10-08T18:58:52Z","updated_at":"2015-08-07T13:01:41Z","pushed_at":"2015-09-15T09:38:30Z","git_url":"git://github.com/gravity-platform/doc.git","ssh_url":"git@github.com:gravity-platform/doc.git","clone_url":"https://github.com/gravity-platform/doc.git","svn_url":"https://github.com/gravity-platform/doc","homepage":"https://gravity-platform-docs.nova.scapp.io/","size":676,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"develop"}},"_links":{"self":{"href":"https://api.github.com/repos/gravity-platform/doc/pulls/7"},"html":{"href":"https://github.com/gravity-platform/doc/pull/7"},"issue":{"href":"https://api.github.com/repos/gravity-platform/doc/issues/7"},"comments":{"href":"https://api.github.com/repos/gravity-platform/doc/issues/7/comments"},"review_comments":{"href":"https://api.github.com/repos/gravity-platform/doc/pulls/7/comments"},"review_comment":{"href":"https://api.github.com/repos/gravity-platform/doc/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/gravity-platform/doc/pulls/7/commits"},"statuses":{"href":"https://api.github.com/repos/gravity-platform/doc/statuses/12db499258ea4e00c3c430feb182990ba26bb220"}}}}