Skip to content

docs(exapp): how HaRP and the ExApp proxy match routes #15980

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oleksandr-nc wants to merge 1 commit into
base: master
Choose a base branch
from
+17 −8
Open

docs(exapp): how HaRP and the ExApp proxy match routes #15980

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions developer_manual/exapp_development/development_overview/ExAppLifecycle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,12 @@ You can define any custom container startup logic here if needed.
Heartbeat
*********

The ``GET /heartbeat`` method is called periodically by Nextcloud to check the ExApp health status,
i.e. if its webserver is running and receiving requests.
AppAPI calls ``GET /heartbeat`` after installing, updating or enabling the ExApp, until it answers,
to check that its web server is running.

URL: ``GET http://localhost:2345/heartbeat``

AppAPI expects a response with HTTP status 200.
AppAPI expects HTTP status 200 with ``{"status": "ok"}``.
This step fails if the ExApp does not respond within 10 minutes.

.. note::
Expand Down
4 changes: 2 additions & 2 deletions developer_manual/exapp_development/tech_details/Deployment.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Options
* ``--json-info JSON-INFO`` *[optional]* - ExApp deploy JSON info (json string)

.. warning::
After successful deployment (pull, create, and start container), there is a heartbeat check with a 90 second timeout (will be configurable).
After successful deployment (pull, create, and start container), there is a heartbeat check with a 10 minute timeout.

Manual install for development
******************************
Expand Down Expand Up @@ -125,7 +125,7 @@ Application installation scheme
-------------------------------

1. AppAPI deploys the application and launches it.
2. For `N` seconds (default ``90``), AppAPI checks the ``/heartbeat`` endpoint with a ``GET`` request.
2. For up to 10 minutes, AppAPI checks the ``/heartbeat`` endpoint with a ``GET`` request.
3. AppAPI sends a ``POST`` request to the ``/init`` endpoint. If the ExApp does not implement the ``/init`` endpoint and AppAPI receives a 501 or 404 status code, AppAPI enables the application and goes straight to step 5.
4. The ExApp sends an integer from ``0`` to ``100`` to the OCS endpoint ``apps/app_api/apps/status`` indicating the initialization progress. After sending ``100``, the application is considered initialized.
5. AppAPI sends a ``PUT`` request to the ``/enabled`` endpoint.
Expand Down
15 changes: 12 additions & 3 deletions developer_manual/exapp_development/tech_details/api/routes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Routes
======

All ExApps must declare the routes that are allowed to be accessed via the AppAPI ExApp proxy (``/apps/app_api/proxy/*``).
All ExApps must declare the routes that users and clients may access, through the AppAPI ExApp proxy (``/apps/app_api/proxy/*``) or, with HaRP, directly (``/exapps/<appid>/*``).


Register
Expand Down Expand Up @@ -34,13 +34,22 @@ Example

where the fields are:

- ``url``: the route to be registered on the ExApp side, can be a regex
- ``verb``: the HTTP verb that the route will accept, can be a comma separated list of verbs
- ``url``: the route to be registered on the ExApp side, a regex matched from the start of the decoded request path, which begins with ``/`` (e.g. ``^/api/.*``); only HaRP matches it case-sensitively
- ``verb``: the HTTP verbs that the route accepts, a comma separated list (e.g. ``GET,POST``)
- ``access_level``: the name of the access level required to access the route, PUBLIC - public access without auth, USER - Nextcloud user auth required, ADMIN - admin user required
- ``headers_to_exclude``: a JSON-encoded string of an array of strings, the headers that the ExApp wants to be excluded from the request to it
- ``bruteforce_protection``: a JSON-encoded string of an array of numbers, the HTTP status codes that must trigger the bruteforce protection


Matching
^^^^^^^^

The first route whose ``url`` matches the path and whose ``verb`` lists the method decides the access level; ``HEAD`` is accepted wherever ``GET`` is.
Other methods get ``405``, except ``404`` from the ExApp proxy for the ones it serves: ``GET``, ``HEAD``, ``POST``, ``PUT``, ``DELETE``.
HaRP applies the highest access level among the readings of a path (letter case, a trailing slash, ``;`` parameters, an escaped ``/``), so write a route for a directory as ``^/img(/.*)?$``.
Paths with ``.`` or ``..`` segments and the ``/heartbeat``, ``/init`` and ``/enabled`` endpoints are refused.


Unregister
^^^^^^^^^^

Expand Down
Loading