Merge pull request #307 from kuzzleio/111-dedidacted-kuzzle-event-sec…

…tion

Move kuzzle event to a new doc section

src/elasticsearch-cookbook/index.md

@@ -1,7 +1,7 @@
 ---
 layout: category-childrens.html
 title: Elasticsearch Cookbook
-order: 700
+order: 800
 description: Learn how to query persistent data in Kuzzle
 icon: fa-book
 ---

src/kuzzle-events/auth/index.md

@@ -0,0 +1,18 @@
+---
+layout: full.html
+algolia: true
+title: auth
+description: list of events emitted by the auth controller
+order: 200
+---
+
+# auth
+
+Events triggered when a request is treated in the [`auth` controller]({{ site_base_path }}api-documentation/controller-auth)
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `auth:after<Action>` | Pipe | All actions in `auth` controller trigger an event after executing | Type: Request |
+| `auth:before<Action>` | Pipe | All actions in `auth` controller trigger an event before executing | Type: Request |
+| `auth:error<Action>` | Pipe | When an error occurred during an action in `auth` controller, an event error is triggered | Type: Request |
+| `auth:strategyAuthenticated` | Pipe | Triggered after an authentication success on passport wrapper, and before resolving the user. | Type: Object.<br>{strategy, content}<br>`strategy` is the used strategy's name<br>`content` is the authenticated User object |

src/kuzzle-events/bulk/index.md

@@ -0,0 +1,17 @@
+---
+layout: full.html
+algolia: true
+title: bulk
+description: list of events emitted by the bulk controller
+order: 200
+---
+
+# bulk
+
+Events triggered when a request is treated in the [`bulk` controller]({{ site_base_path }}api-documentation/controller-bulk)
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `bulk:afterImport` | Pipe | The `import` action in `bulk` controller triggers an event after executing | Type: Request |
+| `bulk:beforeImport` | Pipe | The `import` action in `bulk` controller triggers an event before executing | Type: Request |
+| `bulk:errorImport` | Pipe | When an error occurred during the action `import` in `bulk` controller, an event error is triggered | Type: Request |

src/kuzzle-events/collection/index.md

@@ -0,0 +1,17 @@
+---
+layout: full.html
+algolia: true
+title: collection
+description: list of events emitted by the collection controller
+order: 200
+---
+
+# collection
+
+Events triggered when a request is treated in the [`collection` controller]({{ site_base_path }}api-documentation/controller-collection).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `collection:after<Action>` | Pipe | All actions in `collection` controller trigger an event after executing | Type: Request |
+| `collection:before<Action>` | Pipe | All actions in `collection` controller trigger an event before executing | Type: Request |
+| `collection:error<Action>` | Pipe | When an error occurred during an action in `collection` controller, an event error is triggered | Type: Request |

src/kuzzle-events/core/index.md

@@ -0,0 +1,26 @@
+---
+layout: full.html
+algolia: true
+title: core
+description: list of events emitted to synchronize Kuzzle server instances in a cluster
+order: 200
+---
+
+# core
+
+Events triggered to synchronize Kuzzle server instances in a cluster.
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `core:kuzzleStart` | Hook | Emitted when Kuzzle is started | / |
+| `core:hotelClerk:addSubscription` | Hook | Sends a diff containing the filters and internal hotelClerk updates    | Array of `hcR` object |
+| `core:hotelClerk:join` | Hook | Sends hotelClerk diff when a room is joined | `hcR` object |
+| `core:hotelClerk:removeRoomForCustomer` | Hook | Sends the room unsubscription information if it changed | {connection, roomId} |
+| `core:indexCache:add` | Hook | Triggered when data is added to Kuzzle's index cache | {index, collection} |
+| `core:indexCache:remove` | Hook | Triggered if some data were actually removed from Kuzzle's index cache | {index, collection} |
+| `core:indexCache:reset` | Hook | Triggered if the indexCache is reset | {index} |
+| `core:overload` | Hook | Triggered when the overload cache is filling up | Overload percentage. Type: Number |
+| `core:profileRepository:save` | Hook | Triggered when a profile is created or updated | {_id, policies} |
+| `core:profileRepository:delete` | Hook | Triggered when a profile is deleted | {_id} |
+| `core:roleRepository:save` | Hook | Triggered when a role is created or updated | {_id, controllers} |
+| `core:roleRepository:delete` | Hook | Triggered when a role is deleted | {_id} |

src/kuzzle-events/document/index.md

@@ -0,0 +1,17 @@
+---
+layout: full.html
+algolia: true
+title: document
+description: list of events emitted by the document controller
+order: 200
+---
+
+# document
+
+Events triggered when a request is treated in the [`document` controller]({{ site_base_path }}api-documentation/controller-document).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `document:after<Action>` | Pipe | All actions in `document` controller trigger an event after executing | Type: Request |
+| `document:before<Action>` | Pipe | All actions in `document` controller trigger an event before executing | Type: Request |
+| `document:error<Action>` | Pipe | When an error occurred during an action in `document` controller, an event error is triggered | Type: Request |

src/kuzzle-events/http/index.md

@@ -0,0 +1,13 @@
+---
+layout: full.html
+algolia: true
+title: http
+description: list of events emitted by the http router
+order: 200
+---
+
+# http
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `http:options` | Pipe | Triggered whenever a HTTP OPTIONS methods is handled | Type: Request |

src/kuzzle-events/index.md

@@ -0,0 +1,15 @@
+---
+layout: category-childrens.html
+title: Kuzzle events
+order: 700
+description: Learn about Kuzzle Events
+icon: fa-eye
+---
+
+# Kuzzle events
+
+Welcome to the kuzzle events documentation!
+
+Every time Kuzzle receives a request coming from a client, it routes it towards a Controller and an Action, which processes it and sends the result back to the client. Each step of this life-cycle triggers an event. Here are the different types of events that Plugins can listen to.
+
+There are two kind of events, `pipes` and `hooks`. Report to the [Plugin Reference documentation]({{ site_base_path }}plugins-reference/plugins-features/adding-pipes/#) for more details on how to listen to them.

src/kuzzle-events/index/index.md

@@ -0,0 +1,18 @@
+---
+layout: full.html
+algolia: true
+title: index
+description: list of events emitted by the index controller
+order: 200
+---
+
+# index
+
+Events triggered when a request is treated in the [`index` controller]({{ site_base_path }}api-documentation/controller-index).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `index:after<Action>` | Pipe | All actions in `index` controller trigger an event after executing  | Type: Request |
+| `index:before<Action>` | Pipe | All actions in `index` controller trigger an event before executing | Type: Request |
+| `index:error<Action>` | Pipe | When an error occurred during an action in `index` controller, an event error is triggered | Type: Request |
+

src/kuzzle-events/internal-broker/index.md

@@ -0,0 +1,20 @@
+---
+layout: full.html
+algolia: true
+title: internalBroker
+description: list of events emitted by Kuzzle internal broker
+order: 200
+---
+
+# internalBroker
+
+<aside class="warning">Internal use only</aside>
+
+Events triggered by the Kuzzle internal message broker, used to transmit data between Kuzzle instances.
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `internalBroker:connected` | Hook | Triggered when the internal broker is connected    | Type: String.<br> `'Connected to Kuzzle server'` |
+| `internalBroker:error` | Hook | Triggered when an error occured in internal broker | Type: Object.<br> {host, port, message, retry} |
+| `internalBroker:reregistering` | Hook | Triggered when the internal broker is reregistered | Type: String.<br> `'Re-registering room: ' + room` |
+| `internalBroker:socketClosed` | Hook | Triggered when the socket is closed | Type: String |

src/kuzzle-events/ms/index.md

@@ -0,0 +1,17 @@
+---
+layout: full.html
+algolia: true
+title: ms (memoryStorage)
+description: list of events emitted by the memoryStorage controller
+order: 200
+---
+
+# ms (memoryStorage)
+
+Events triggered when a request is sent to the [`memoryStorage` controller]({{ site_base_path }}api-documentation/controller-memory-storage).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+|`ms:after<Action>` | Pipe | All actions in `memoryStorage` controller trigger an event after executing | Type: Request |
+|`ms:before<Action>` | Pipe | All actions in `memoryStorage` controller trigger an event before executing | Type: Request |
+| `ms:error<Action>` | Pipe | When an error occurred during an action in `ms` controller, an event error is triggered | Type: Request |

src/kuzzle-events/plugin-events/index.md

@@ -0,0 +1,30 @@
+---
+layout: full.html
+algolia: true
+title: [Plugin events]
+description: list of events emitted by plugins
+order: 100
+---
+
+# [Plugin events]
+
+[Plugins]({{ site_base_path }}plugins-reference/plugins-features/adding-controllers) may add new controllers and actions to Kuzzle's API. These do not differ from native controllers/actions and these, too, trigger events that can be listened by plugins.
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `<pluginName>/<controller>:after<Action>` | Pipe | Triggered after the action `action` of the controller `controller` added by the plugin `pluginName` has completed | Type: Request |
+| `<pluginName>/<controller>:before<Action>` | Pipe | Triggered before the action `action` of the controller `controller` added by the plugin `pluginName` has started | Type: Request |
+| `<pluginName>/<controller>:error<Action>` | Pipe | When an error occurred during an action in `controller` controller, an event error is triggered | Type: Request |
+
+**Example:**
+
+The plugin `foo` adds a controller named `fooController`, containing an action named `fooAction`.
+
+When an API request invokes this new API route, Kuzzle will automatically trigger the following events:
+
+* `foo/fooController:beforeFooAction` (before the request starts)
+* `foo/fooController:afterFooAction` (after the request completes)
+
+And in case of error, will trigger the event:
+
+* `foo/fooController:errorFooAction`

src/kuzzle-events/realtime/index.md

@@ -0,0 +1,17 @@
+---
+layout: full.html
+algolia: true
+title: realtime
+description: list of events emitted by the realtime controller
+order: 200
+---
+
+# realtime
+
+Events triggered when a request is sent to the [`realtime` controller]({{ site_base_path }}api-documentation/controller-realtime).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+|`realtime:after<Action>` | Pipe | All actions in `realtime` controller trigger an event after executing | Type: Request |
+|`realtime:before<Action>` | Pipe | All actions in `realtime` controller trigger an event before executing | Type: Request |
+|`realtime:error<Action>` | Pipe | When an error occurred during an action in `realtime` controller, an event error is triggered | Type: Request |

src/kuzzle-events/request/index.md

@@ -0,0 +1,18 @@
+---
+layout: full.html
+algolia: true
+title: request
+description: list of global events emitted on requests execution 
+order: 200
+---
+
+# request
+
+Global events triggered on requests execution.
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+|`request:onAuthorized` | Pipe | Triggered when a request passed authorization checks and is ready to be processed. Triggered before any `<controller>:before<Action>` event | Type: Request |
+|`request:onError` | Pipe | Triggered when a request execution fails. Triggered after any `<controller>:after<Action>` event | Type: Request |
+|`request:onSuccess` | Pipe | Triggered when a request execution succeeds. Triggered after any `<controller>:after<Action>` event | Type: Request |
+|`request:onUnauthorized` | Pipe | Triggered when a request failed authorization checks and is about to be rejected with a `401` error code. | Type: Request |

src/kuzzle-events/room/index.md

@@ -0,0 +1,16 @@
+---
+layout: full.html
+algolia: true
+title: room
+description: list of events emitted on subscription rooms activity
+order: 200
+---
+
+# room
+
+Events triggered on subscription rooms activity.
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `room:new` | Pipe | Triggered when a new room is added in the rooms list. You can't modify the input on this event | Type: Object. <br> `{roomId, index, collection, formattedFilters}` |
+| `room:remove` | Pipe | Triggered after a room is removed from the list. You can't modify the input on this event | Type: String.<br> The room id |

src/kuzzle-events/security/index.md

@@ -0,0 +1,19 @@
+---
+layout: full.html
+algolia: true
+title: security
+description: list of events emitted by the security controller
+order: 200
+---
+
+# security
+
+Events triggered when a request is sent to the [`security` controller]({{ site_base_path }}api-documentation/controller-security).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `security:after<Action>` | Pipe | All actions in `security` controller trigger an event after executing | Type: Request |
+| `security:before<Action>` | Pipe | All actions in `security` controller trigger an event before executing | Type: Request |
+| `security:formatUserForSerialization` | Pipe | Triggered before serializing a user. Useful to clean a user like attribute `password` | Type: User |
+| `security:error<Action>` | Pipe | When an error occurred during an action in `security` controller, an event error is triggered | Type: Request |
+

src/kuzzle-events/server/index.md

@@ -0,0 +1,18 @@
+---
+layout: full.html
+algolia: true
+title: server
+description: list of events emitted by the server controller
+order: 200
+---
+
+# server
+
+Events triggered on server special events or when a request is sent to the [`server` controller]({{ site_base_path }}api-documentation/controller-server).
+
+| Event | Type | Description | Payload |
+|-------|------|-------------|---------|
+| `server:after<Action>` | Pipe | All actions in `server` controller trigger an event after executing  | Type: Request |
+| `server:before<Action>` | Pipe | All actions in `server` controller trigger an event before executing | Type: Request |
+| `server:error<Action>` | Pipe | When an error occurred during an action in `server` controller, an event error is triggered | Type: Request |
+