feat(webhooks): add emsco_webhook, emsch_webhook_event, ems_clear_http_caches twig functions (#1477)

Author: theus77

.vitepress/nav/sidebar.ts

@@ -46,6 +46,7 @@ const sidebar: DefaultTheme.SidebarMulti = {
                     collapsed: true,
                     items: [
                         { text: 'Login', link: '/elasticms-admin/api/login' },
+                        { text: 'Monitoring', link: '/elasticms-admin/api/monitoring' },
                         { text: 'Webhook', link: '/elasticms-admin/api/webhook' },
                     ]
                 },

elasticms-admin/api/monitoring.md

@@ -87,3 +87,23 @@ The `redirects/favicon.json.twig` template:
         })|json_encode|raw -}}
 {%- endblock request -%}
 ```
+
+## emsch_webhook_event
+
+This function returns an `EMS\ClientHelperBundle\Helper\Webhook` instance for the current request's
+webhook.
+
+If the current request is not a valid webhook request, an exception will be thrown.
+
+A webhook request is always a POST request and must return JSON.
+
+See [webhook](../../../elasticms-admin/api/webhook.md) for more information.
+
+```twig
+{%- set event = emsch_webhook_event() -%}
+{%- if event.name == 'clear-cache' -%}
+    {%- do ems_clear_http_caches() -%}
+    {%- set success = true -%}
+{%- endif -%}
+{{- { success: success|default(false) }|json_encode|raw -}}
+```

src/dev/client-helper-bundle/Twig/functions.md

@@ -398,3 +398,27 @@ emsch_demo_asset_in_archive:
         defaults: { hash: 253b903b1fb3ac30975ae9844a0352a65cdcfa3d, maxAge: 3600 }
         controller: 'EMS\CommonBundle\Controller\FileController::assetInArchive'
 ```
+
+## HTTP Cache Controller
+
+This controller allows you to interact with the configured reverse proxy (e.g. Varnish) that serve
+your skeleton.
+
+### Handle ElasticMS webhooks event
+
+This controller's method will handle regular ElasticMS webhooks event to invalidate caches base on
+the event. Depending the event, part of all of the caches will be purged.
+
+Example of route:
+
+```yaml
+emsch_admin_webhook:
+    config:
+        path: '/_admin_webhook'
+        method: [POST]
+        host: 'localhost'
+        controller: 'emsch.controller.http_cache::adminWebhook'
+```
+
+In order to avoid unnecessary exposition you should defined a host in that route that is available
+from the admin but not from the Internet.

src/dev/client-helper-bundle/routing.md

@@ -631,3 +631,47 @@ Use php \intval function on input
 ```twig
 {% set size = app.request.query.get('size', 0)|ems_int %}
 ```
+
+### ems_clear_http_caches
+
+Calls the configured reverse proxy services to invalidate part or all of their caches.
+
+It accepts one optional argument:
+
+- **`URL or Tags` (optional)**:
+    - If it contains an empty array (default value), a full cache purge will be sent.
+    - If it is a string starting with `/`, a cache clear by URL will be sent.
+    - Otherwise, a cache clear by tags will be sent.
+
+#### Example of a cache clear route
+
+The URL is triggered by a `clear-cache` webhook event, at the endpoint `//localhost/_clear_cache`.
+
+Depending on the event data:
+
+- If it contains a **`tags`** attribute (string or array of strings), a tag-based cache clear will
+  be sent.
+- If it contains a **`url`** attribute (string), a URL-based cache clear will be sent.
+- Otherwise, a full cache purge will be sent.
+
+The `emsch_clear_cache` route:
+
+```yaml
+emsch_clear_cache:
+    config:
+        path: '/_clear_cache'
+        method: [POST]
+        host: 'localhost'
+    template_static: template/admin/clear-cache.html.twig
+```
+
+The `template/admin/clear-cache.html.twig` twig:
+
+```twig
+{%- set event = emsch_webhook_event() -%}
+{%- if event.name == 'clear-cache' -%}
+    {%- do ems_clear_http_caches(event.data.tags|default(event.data.url|default([]))) -%}
+    {%- set success = true -%}
+{%- endif -%}
+{{- { success: success|default(false) }|json_encode|raw -}}
+```

src/dev/common-bundle/twig.md

@@ -302,3 +302,17 @@ Function that generate a warning message to the user
   }) %}
 {% endif %}
 ```
+
+## emsco_webhook
+
+Dispatches a custom webhook event to registered clients.  
+This function takes two parameters:
+
+- **event name** (string)
+- **data** (array)
+
+```twig
+{% do emsco_webhook('custom-event', {
+    'foo': 'bar',
+}) %}
+```

src/dev/core-bundle/twig/core.md

@@ -0,0 +1,25 @@
+# Monitoring
+
+You can monitor an instance of elasticMS admin via the URL `/status`. This URL is declined in 3
+formats:
+
+- HTML: `/status`
+- JSON: `/status.json`
+- XML: `/status.xml`
+
+If something goes wrong with the elasticsearch cluster an HTTP call will return a `500` or a `503`
+HTTP return code.
+
+## Extra parameters
+
+By default, the `/status` URL does not return a `500` HTTP error if there is jobs in error or
+message stuck in the queue. But, some limits may be defined to do so:
+
+- `jobs_pending_limit`: if defined, the URL will return a `500` code if the number of pending jobs
+  is reached
+- `jobs_failed_limit`: if defined, the URL will return a `500` code if the number of failed jobs is
+  reached
+- `bus_queue_limit`: if defined, the URL will return a `500` code if the number of messages in the
+  bus queue is reached
+- `bus_failed_limit`: if defined, the URL will return a `500` code if the number of messages in the
+  failed queue is reached

src/elasticms-admin/api/monitoring.md

@@ -22,6 +22,10 @@ In case of success you'll get a JSON with those fields:
 - `id`: a UUID of the subscription you just created
 - `secret`: a secret that will be used to sign calls to the provided endpoint URL
 
+Also, around 40 seconds after the registration, a
+[`validate_webhook_subscription`](#validate-subscription) webhook event is sent to the provided
+`endpointUrl`.
+
 ## Delete a subscription (unsubscribe)
 
 This HTTP call will unsubscribe the subscription for the provided UUID:
@@ -68,6 +72,18 @@ Each webhook call's body contains a JSON with two fields:
 
 ## Events
 
+### Validate subscription
+
+This event is sent 40 seconds after the registration. The registered client must return a 200 to
+this call in order keep it working. This event may be resent from time to time by the backend in
+order to monitor the webhook connection. A `200` response is still required to keep the connection
+active.
+
+The structure of the webhook `data` is:
+
+- `secret` (string): The subscription's secret.
+- `events` (string[]): The list of registered events.
+
 ### Content Publish to
 
 To register to this event, you have to specify on which environment you want by ending the string

src/elasticms-admin/api/webhook.md

@@ -582,3 +582,27 @@ Options:
       --current-revision-only                  Translations will be updated only is the source revision is still a current revision
       --base-url[=BASE-URL]                    Base url, in order to generate a download link to the error report
 ```
+
+## Dispatch a webhook event
+
+Command to trigger a custom webhook event to registered clients.
+
+```bash
+Usage:
+  emsco:webhook:dispatch <event-name> [<data>]
+
+Arguments:
+  event-name            Name of the webhook event
+  data                  Data (JSON format) [default: "{}"]
+
+Options:
+  -h, --help            Display help for the given command. When no command is given display help for the list command
+  -q, --quiet           Do not output any message
+  -V, --version         Display this application version
+      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
+  -n, --no-interaction  Do not ask any interactive question
+  -e, --env=ENV         The Environment name. [default: "dev"]
+      --no-debug        Switch off debug mode.
+      --profile         Enables profiling (requires debug).
+  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
+```

src/elasticms-admin/commands/commands.md

@@ -368,6 +368,30 @@ Bollean variable, if specified to `true` all elasticsearch query will be delegat
 And then you'll need to login on an admin first via the `ems:admin:login` command. By default, this
 variable is set to `false`.
 
+### EMS_HTTP_CACHES
+
+Available since release **6.10.0**.
+
+This environment variable is used to define all reverse proxy services in front of your website.  
+Currently, **Varnish** is the only supported reverse proxy.
+
+It is used by the `HttpCacheManager` to invalidate cache services such as Varnish.
+
+```dotenv
+EMS_HTTP_CACHES='[{"header":"x-varnish","url":"http://varnish.localhost/","headers":{"X-Invalidate-Token":"devsecret"}}]'
+```
+
+This variable must contain a JSON-encoded array of objects. Each object is structured as follows:
+
+- `header`: The name of the HTTP request header used by the `HttpCacheManager` to detect that the
+  request has been forwarded by a reverse proxy. This field is required.
+- `url`: The internal URL of the reverse proxy that the HttpCacheManager will use to communicate
+  with it. This field is required.
+- `headers` (optional): A set of HTTP headers that the HttpCacheManager will include when
+  communicating with the reverse proxy. Default to `[]`.
+- `verify_ssl` (optional): Whether the certificate of the reverse proxy should be verified. Defaults
+  to `true`.
+
 ## Elasticms Form Bundle variables
 
 ### EMSF_HASHCASH_DIFFICULTY