mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-02 17:59:36 +07:00
156 lines
4.7 KiB
ReStructuredText
156 lines
4.7 KiB
ReStructuredText
.. _ex_app_lifecycle:
|
|
|
|
ExApp lifecycle
|
|
===============
|
|
|
|
The ExApp lifecycle is a set of communication rules (or protocol) between Nextcloud and ExApp.
|
|
They are required as for the microservice architecture of ExApp.
|
|
This section is an overview, more details on that here: :ref:`app_installation_flow`, :ref:`app_deployment`.
|
|
|
|
|
|
.. _ex_app_lifecycle_methods:
|
|
|
|
|
|
ExApp lifecycle methods
|
|
-----------------------
|
|
|
|
When ExApp is being installed in Nextcloud, there are several lifecycle steps happening.
|
|
The ExApp lifecycle requires the following API endpoint handlers (order is preserved):
|
|
|
|
- 0. ``healthcheck``: Docker container healthcheck.
|
|
- 1. ``/heartbeat``: **[required]** ExApp heartbeat handler.
|
|
- 2. ``/init``: **[optional]** ExApp initialization handler.
|
|
- 3. ``/enabled``: **[required]** ExApp enable/disable handler.
|
|
|
|
|
|
Healthcheck
|
|
***********
|
|
|
|
Docker allows you to define a custom healthcheck script for your container (specified in the Dockerfile).
|
|
You can define here if needed custom container startup logic.
|
|
|
|
.. note::
|
|
|
|
AppAPI healthcheck timeout is 15 minutes.
|
|
|
|
|
|
Heartbeat
|
|
*********
|
|
|
|
The ``GET /heartbeat`` method is called periodically by Nextcloud to check the ExApp health status,
|
|
if its webserver is running and receiving requests.
|
|
|
|
URL: ``GET http://localhost:2345/heartbeat``
|
|
|
|
AppAPI expects a response with HTTP status 200.
|
|
This step fails if the ExApp does not respond within 10 minutes.
|
|
|
|
.. note::
|
|
|
|
This endpoint should be available **without AppAPIAuth authentication**.
|
|
There is a 10 minutes timeout for the ExApp to startup and respond to the ``/heartbeat`` request.
|
|
|
|
|
|
.. _ex_app_lifecycle_init:
|
|
|
|
|
|
Init
|
|
****
|
|
|
|
The ``POST /init`` endpoint is called after the ExApp is enabled in Nextcloud.
|
|
This is a trigger for ExApp to start its initialization process, e.g. downloading models, starter data, etc.
|
|
|
|
.. note::
|
|
|
|
Default init timeout (``init_timeout``) is 40 minutes. It can be changed by admin in AppAPI settings
|
|
or via CLI command ``occ config:app:set app_api init_timeout --value 40 --type mixed``.
|
|
|
|
URL: ``POST http://localhost:2345/init``
|
|
|
|
AppAPI expects a response with HTTP status 200.
|
|
|
|
.. note::
|
|
|
|
If ExApp doesn't not implement ``/init`` endpoint and AppAPI receives ``HTTP 501 NOT IMPLEMENTED`` or ``HTTP 404 NOT FOUND`` response,
|
|
AppAPI enables the ExApp.
|
|
|
|
The ExApp should update the init progress via the ``PUT /ocs/v2.php/apps/app_api/ex-app/status`` API request,
|
|
with ``{ "progress": <number> }`` payload.
|
|
|
|
|
|
Enabled
|
|
*******
|
|
|
|
The ``PUT /enabled?enabled=1|0`` method is called when the ExApp is enabled or disabled in Nextcloud.
|
|
The ``enabled`` query parameter is used to determine the ExApp state: 1 - enabled, 0 - disabled.
|
|
|
|
|
|
- ``PUT http://localhost:2345/enabled?enabled=1`` - enable ExApp, during this call ExApp should register all needed APIs
|
|
- ``PUT http://localhost:2345/enabled?enabled=0`` - disable ExApp, during this call ExApp should unregister all APIs
|
|
|
|
AppAPI expects a response with HTTP status 200. Any other status code will be considered as an error.
|
|
|
|
.. note::
|
|
|
|
AppAPI timeout for the ``enabled`` handler is 30 seconds.
|
|
|
|
|
|
ExApp lifecycle scheme
|
|
----------------------
|
|
|
|
Let's review a simple ExApp lifecycle scheme:
|
|
|
|
|
|
.. mermaid::
|
|
|
|
sequenceDiagram
|
|
participant Nextcloud
|
|
participant ExApp
|
|
loop Heartbeat
|
|
Nextcloud->>ExApp: HTTP GET /heartbeat
|
|
ExApp-->>Nextcloud: /heartbeat HTTP 200
|
|
end
|
|
Nextcloud->>ExApp: HTTP POST /init
|
|
ExApp->>Nextcloud: /init HTTP OK 200
|
|
loop Init
|
|
ExApp->>ExApp: Download models, starter data, etc.
|
|
ExApp-->>Nextcloud: PUT /ocs/v2.php/apps/app_api/ex-app/status { "progress": 50 }
|
|
end
|
|
Nextcloud->>ExApp: HTTP PUT /enabled?enabled=1
|
|
ExApp-->>Nextcloud: Register all needed APIs via OCS API
|
|
ExApp->>Nextcloud: /enabled HTTP 200
|
|
Nextcloud->>ExApp: HTTP PUT /enabled?enabled=0
|
|
ExApp-->>Nextcloud: Unregister all APIs via OCS API
|
|
ExApp->>Nextcloud: /enabled HTTP 200
|
|
|
|
|
|
Nextcloud-side ExApp lifecycle methods
|
|
--------------------------------------
|
|
|
|
The Nextcloud-side ExApp lifecycle methods are the OCS APIs.
|
|
You can find available AppAPI Nextcloud OCS APIs :ref:`here <app_api_nextcloud_apis>`.
|
|
|
|
.. note::
|
|
|
|
ExApp should register all needed APIs during the ``enabled`` method call.
|
|
E.g. UI (:ref:`top-menu <top_menu_section>`, :ref:`filesactionmenu <file_actions_menu_section>`), :ref:`occ commands <occ_command>`, etc.
|
|
|
|
|
|
AppAPI Authentication
|
|
---------------------
|
|
|
|
Nextcloud requests to the ExApp are secured with :ref:`AppAPIAuth <app_api_auth>`.
|
|
The ExApp should validate the authentication using the same algorithm as AppAPI does.
|
|
|
|
.. note::
|
|
|
|
Is it up to the developer to apply the rate limits, bruteforce protection, and other security measures
|
|
to the ExApp API endpoints.
|
|
|
|
|
|
Cookies
|
|
*******
|
|
|
|
Along with the AppAPIAuth, ExApp can utilize the Nextcloud cookies of the authenticated user,
|
|
who made the request to the ExApp.
|