From 8902bb356f6b67c31e54cb23c27cd375f2f4ccdb Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Mon, 30 May 2016 17:53:10 +0200 Subject: [PATCH] Improves documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Change-Id: I7a93b69d56912f396aa7819149038746aa59e620 Signed-off-by: José Bollo --- doc/afb-application-writing.html | 223 ++++++++++++++++++++++++++++++++++++++- doc/afb-application-writing.md | 176 +++++++++++++++++++++++++++++- doc/afb-plugins-overview.html | 162 +++++++++++++++++----------- doc/afb-plugins-overview.md | 31 ++++-- doc/afb-tests-overview.html | 8 +- doc/afb-tests-overview.md | 4 +- 6 files changed, 522 insertions(+), 82 deletions(-) diff --git a/doc/afb-application-writing.html b/doc/afb-application-writing.html index e0bb42c0..2547cee9 100644 --- a/doc/afb-application-writing.html +++ b/doc/afb-application-writing.html @@ -26,6 +26,29 @@ Author: José Bollo + +
  • Format of replies +
    • @@ -105,6 +128,9 @@ the socket connection can not be used to authenticate a client.

    by using a commonly shared secret named token and the identification of the client named session.

    +

    The examples token-websock.qml and afb-client are demonstrating +how authentication and sessions are managed.

    +

    Handling sessions

    @@ -112,7 +138,12 @@ of the client named session.

    instances. This of importance for plugins running as service because they may have to separate the data of each client.

    -

    For common HTML5 browser running an HTML5 application.

    +

    For HTML5 applications, the web runtime handles the cookie of session +that the binder afb-daemon automatically sets.

    + +

    In any case, the session identifier can be set using the parameters +uuid or x-afb-uuid in the request uri. That is understood +by HTTP requests and by the negociation of websockets.

    Exchanging tokens

    @@ -122,7 +153,193 @@ and its client: the application. This initial secret is the initial token.

    For each of its client application, the binder manages a current active -token. The initial token is the default active token. It is the expected -token for new clients.

    +token for the session. This authentication token can be a requirement for +accessing some methods.

    + +

    The token must be passed in the request uri on HTTP or at connecting +websockets using the parameter token or x-afb-token.

    + +

    To ensure security, tokens must be refreshed periodically.

    + + +

    Example of session management

    + +

    For the following exmples, we suppose that you launched afb-daemon like that or similar:

    + +
    $ afb-daemon --port=1234 --token=123456 [...]
+
    + +

    with the expectation that the plugin AuthLogin is loaded.

    + + +

    Using curl

    + +

    First, connects with the initial token, 123456:

    + +
    $ curl http://localhost:1234/api/auth/connect?token=123456
+{
+  "jtype": "afb-reply",
+  "request": {
+ "status": "success",
+ "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
+ "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
+  },
+  "response": {"token": "A New Token and Session Context Was Created"}
+}
+
    + +

    It returns an answer containing the uuid of the session, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015, +and the refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.

    + +

    Let check that it is available:

    + +
    $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+  "jtype": "afb-reply",
+  "request": {"status":"success"},
+  "response": {"isvalid":true}
+}
+
    + +

    It works! So try now to refresh the token:

    + +
    $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+  "jtype": "afb-reply",
+  "request": {
+ "status":"success",
+ "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
+  },
+  "response": {"token":"Token was refreshed"}
+}
+
    + +

    Let now close the session:

    + +
    curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+  "jtype": "afb-reply",
+  "request": {"status": "success"},
+  "response": {"info":"Token and all resources are released"}
+}
+
    + +

    So now, checking for the uuid will be refused:

    + +
    curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+  "jtype": "afb-reply",
+  "request": {
+ "status": "failed",
+ "info": "invalid token's identity"
+  }
+}
+
    + + +

    Using afb-client-demo

    + +

    Here is an example of exchange using afb-client-demo:

    + +
    $ afb-client-demo ws://localhost:1234/api?token=123456
+auth connect
+ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success",
+   "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"},
+   "response":{"token":"A New Token and Session Context Was Created"}}
+auth check
+ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+auth refresh
+ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
+   "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
+auth check
+ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+auth refresh
+ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
+   "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
+
    + +

    Then you leave. And can reconnect as below:

    + +
    $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check
+ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+
    + +

    The same can be continued using curl:

    + +
    $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1
+{"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+
    + + +

    Format of replies

    + +

    The replies are made of one javascript object returned using JSON serialization.

    + +

    This object containts at least 2 mandatory fields of name jtype and request +and an optionnal field of name response.

    + + +

    Field jtype

    + +

    The field jtype must have a value of type string equel to “afb-reply”.

    + + +

    Field request

    + +

    The field request must have a value of type object. This request object +has at least one field named status and four optionnal fields of name +info, token, uuid, reqid.

    + + +

    Subfield request.status

    + +

    status must have a value of type string. This string is equal to “success” +only in case of success.

    + + +

    Subfield request.info

    + +

    info is of type string and represent optionnal the information added to the reply.

    + + +

    Subfield request.token

    + +

    token is of type string. It is sent either on the creation of the +session or when the token is refreshed.

    + + +

    Subfield request.uuid

    + +

    uuid is of type string. It is sent on the creation of the session.

    + + +

    Subfield request.reqid

    + +

    reqid is of type string. It is sent in response of HTTP requests +that added a parameter of name reqid or x-afb-reqid. The value +sent in the reply is the exact value received on the request.

    + + +

    Field response

    + +

    This field response optionnaly containts the object returned with successful replies.

    + + +

    Template

    + +

    This is a template of replies:

    + +
    {
+  "jtype": "afb-reply",
+  "request": {
+   "status": "success",
+   "info": "informationnal text",
+   "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
+   "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
+   "reqid": "application-generated-id-23456"
+ },
+  "response": ....any response object....
+}
+
    diff --git a/doc/afb-application-writing.md b/doc/afb-application-writing.md index 70dde783..a2bbf4d5 100644 --- a/doc/afb-application-writing.md +++ b/doc/afb-application-writing.md @@ -71,13 +71,21 @@ For this reason, the binder should authenticate the application by using a commonly shared secret named token and the identification of the client named session. +The examples **token-websock.qml** and **afb-client** are demonstrating +how authentication and sessions are managed. + ### Handling sessions Plugins and features of the binder need to keep track of the client instances. This of importance for plugins running as service because they may have to separate the data of each client. -For common HTML5 browser running an HTML5 application. +For HTML5 applications, the web runtime handles the cookie of session +that the binder afb-daemon automatically sets. + +In any case, the session identifier can be set using the parameters +**uuid** or **x-afb-uuid** in the request uri. That is understood +by HTTP requests and by the negociation of websockets. ### Exchanging tokens @@ -86,8 +94,170 @@ and its client: the application. This initial secret is the initial token. For each of its client application, the binder manages a current active -token. The initial token is the default active token. It is the expected -token for new clients. +token for the session. This authentication token can be a requirement for +accessing some methods. + +The token must be passed in the request uri on HTTP or at connecting +websockets using the parameter **token** or **x-afb-token**. + +To ensure security, tokens must be refreshed periodically. + +### Example of session management + +For the following exmples, we suppose that you launched **afb-daemon** like that or similar: + + $ afb-daemon --port=1234 --token=123456 [...] + +with the expectation that the plugin **AuthLogin** is loaded. + +#### Using curl + +First, connects with the initial token, 123456: + + $ curl http://localhost:1234/api/auth/connect?token=123456 + { + "jtype": "afb-reply", + "request": { + "status": "success", + "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f", + "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015" + }, + "response": {"token": "A New Token and Session Context Was Created"} + } + +It returns an answer containing the uuid of the session, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015, +and the refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015. + +Let check that it is available: + + $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 + { + "jtype": "afb-reply", + "request": {"status":"success"}, + "response": {"isvalid":true} + } + +It works! So try now to refresh the token: + + $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 + { + "jtype": "afb-reply", + "request": { + "status":"success", + "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9" + }, + "response": {"token":"Token was refreshed"} + } + +Let now close the session: + + curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 + { + "jtype": "afb-reply", + "request": {"status": "success"}, + "response": {"info":"Token and all resources are released"} + } + +So now, checking for the uuid will be refused: + + curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 + { + "jtype": "afb-reply", + "request": { + "status": "failed", + "info": "invalid token's identity" + } + } + +#### Using afb-client-demo + +Here is an example of exchange using **afb-client-demo**: + + $ afb-client-demo ws://localhost:1234/api?token=123456 + auth connect + ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success", + "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"}, + "response":{"token":"A New Token and Session Context Was Created"}} + auth check + ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} + auth refresh + ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", + "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}} + auth check + ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} + auth refresh + ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", + "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}} + +Then you leave. And can reconnect as below: + + $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check + ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} + +The same can be continued using **curl**: + + $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 + {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} + +Format of replies +----------------- + +The replies are made of one javascript object returned using JSON serialization. + +This object containts at least 2 mandatory fields of name **jtype** and **request** +and an optionnal field of name **response**. + +### Field jtype + +The field **jtype** must have a value of type string equel to **"afb-reply"**. + +### Field request + +The field **request** must have a value of type object. This request object +has at least one field named **status** and four optionnal fields of name +**info**, **token**, **uuid**, **reqid**. + +#### Subfield request.status + +**status** must have a value of type string. This string is equal to **"success"** +only in case of success. + +#### Subfield request.info + +**info** is of type string and represent optionnal the information added to the reply. + +#### Subfield request.token + +**token** is of type string. It is sent either on the creation of the +session or when the token is refreshed. + +#### Subfield request.uuid + +**uuid** is of type string. It is sent on the creation of the session. + +#### Subfield request.reqid + +**reqid** is of type string. It is sent in response of HTTP requests +that added a parameter of name **reqid** or **x-afb-reqid**. The value +sent in the reply is the exact value received on the request. + +### Field response + +This field response optionnaly containts the object returned with successful replies. + +### Template +This is a template of replies: + { + "jtype": "afb-reply", + "request": { + "status": "success", + "info": "informationnal text", + "token": "e83b36f8-d945-463d-b983-5d8ed73ba52", + "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1", + "reqid": "application-generated-id-23456" + }, + "response": ....any response object.... + } diff --git a/doc/afb-plugins-overview.html b/doc/afb-plugins-overview.html index b3236886..8c7b50fa 100644 --- a/doc/afb-plugins-overview.html +++ b/doc/afb-plugins-overview.html @@ -15,13 +15,17 @@ Author: Manuel Bachmann

    List of plugins

    -

    Here are the plugins shipped in the source tree: - * Hello World - * Authentication - * Tic Tac Toe - * Audio (2 backends: ALSA/PulseAudio) - * Radio (1 backend: RTLSDR RTL2832U) - * Media (1 backend: Rygel UPnP)

    +

    Here are the plugins shipped in the source tree:

    + + +

    All plugins may not be built, depending on the development libraries present on the system at build time.

    @@ -35,13 +39,17 @@ Author: Manuel Bachmann

    This plugin provides a few unauthenticated requests, all beginning with “ping”, to demonstrate basic binder capabilities.

    -

    Verbs: -* ping: returns a success response -* pingfail: returns a failure response -* pingnull: returns a success response, with an empty JSON response field -* pingbug: does a memory violation (intercepted by the binder) -* pingJson: returns a success response, with a complex JSON response field -* pingevent: broadcasts a global event

    +

    Verbs:

    + + +


    @@ -54,12 +62,16 @@ Author: Manuel Bachmann

    Calling “connect” with a security token will initiate a session, calling “refresh” will issue a new token and invalidate the previous one, calling “logout” will invalidate all tokens and close the session.

    -

    Verbs: -* ping: returns a success response -* connect: creates a session and returns a new token -* refresh: returns a new token -* check: verifies the passed token is valid -* logout: closes the session

    +

    Verbs:

    + + +


    @@ -70,34 +82,46 @@ Author: Manuel Bachmann

    This plugin provides an interactive Tic Tac Toe game where the binder returns the grid as a JSON response.

    -

    Verbs: -* new: starts a new game -* play: asks the server to play -* move: gives a client move -* board: gets the current board state, as a JSON structure -* level: sets the server level -* join: joins an existing board -* undo: undo the last move -* wait: wait for a move

    +

    Verbs:

    + + +


    Audio

    -

    A sample Audio plugin with 2 backends: - * ALSA (mandatory) - * PulseAudio (optional)

    +

    A sample Audio plugin with 2 backends:

    + + +

    This plugin is able to initialize a specific soundcard, define volume levels, channels (mono/stereo…), mute sound, and play a 22,050 Hz PCM stream.

    -

    Verbs: -* ping: returns a success response -* init: initializes backend, on the “default” sound card -* volume: gets or sets volume, in % (0-100) -* channels: gets or sets channels count (1-8) -* mute: gets or sets the mute status (on-off) -* play: gets or sets the playing status (on-off)

    +

    Verbs:

    + + +

    (if PulseAudio development libraries are not found at build time, only ALSA will be available)

    @@ -110,19 +134,27 @@ Author: Manuel Bachmann

    Radio

    -

    A sample AM/FM Radio plugin with 1 backend: - * RTLSDR - Realtek RTL2832U dongles (mandatory)

    +

    A sample AM/FM Radio plugin with 1 backend:

    + + +

    This plugin is able to initialize specific RTL2832U dongles, switch between AM/FM modes, define frequency, mute sound, and play sound (if combining with the audio plugin).

    -

    Verbs: -* ping: returns a success response -* init: initializes backend, looking for plugged-in devices -* power: sets device power status (on-off) -* mode: sets device reception mode (AM-FM) -* freq: sets device frequency (in Hz) -* mute: sets device mute status (on-off) -* play: sets device playing status (on-off)

    +

    Verbs:

    + + +

    (if rtlsdr development libraries are not found at build time, this plugin will not be built)

    @@ -131,21 +163,29 @@ Author: Manuel Bachmann

    Media

    -

    A sample Media Server plugin with 1 backend: - * Rygel

    +

    A sample Media Server plugin with 1 backend:

    + + +

    This plugin is able to detect a local Rygel UPnP media server, list audio files, select an audio file for playback, play/pause/seek in this file, upload an audio file to the server.

    -

    Verbs: -* ping: returns a success response -* init: initializes backend, looking for an active local UPnP server -* list: returns list of audio files, as a JSON structure -* select: select an audio files, by index number (001-…) -* play: plays the currently selected audio file -* stop: stops the currently selected audio file -* pause: pauses the currently selected audio file -* seek: seeks in the currently selected audio file, in seconds -* upload: uploads an audio file, with a POST request

    +

    Verbs:

    + + +

    (if GUPnP/GSSDP development libraries are not fund at build time, this plugin will not be built)

    diff --git a/doc/afb-plugins-overview.md b/doc/afb-plugins-overview.md index 7e351b6a..1986adf3 100644 --- a/doc/afb-plugins-overview.md +++ b/doc/afb-plugins-overview.md @@ -5,13 +5,15 @@ ## List of plugins - Here are the plugins shipped in the source tree: - * Hello World - * Authentication - * Tic Tac Toe - * Audio _(2 backends: ALSA/PulseAudio)_ - * Radio _(1 backend: RTLSDR RTL2832U)_ - * Media _(1 backend: Rygel UPnP)_ + +Here are the plugins shipped in the source tree: + +* Hello World +* Authentication +* Tic Tac Toe +* Audio _(2 backends: ALSA/PulseAudio)_ +* Radio _(1 backend: RTLSDR RTL2832U)_ +* Media _(1 backend: Rygel UPnP)_ All plugins may not be built, depending on the development libraries present on the system at build time. @@ -25,6 +27,7 @@ A sample Hello World plugin for demonstration and learning purposes. This plugin provides a few unauthenticated requests, all beginning with "ping", to demonstrate basic binder capabilities. **Verbs**: + * _ping:_ returns a success response * _pingfail:_ returns a failure response * _pingnull:_ returns a success response, with an empty JSON response field @@ -44,6 +47,7 @@ This plugin provides a few requests to demonstrate the binder's token-based secu Calling "_connect_" with a security token will initiate a session, calling "_refresh_" will issue a new token and invalidate the previous one, calling "_logout_" will invalidate all tokens and close the session. **Verbs**: + * _ping:_ returns a success response * _connect:_ creates a session and returns a new token * _refresh:_ returns a new token @@ -60,6 +64,7 @@ A sample Tic Tac Toe game plugin. This plugin provides an interactive Tic Tac Toe game where the binder returns the grid as a JSON response. **Verbs**: + * _new:_ starts a new game * _play:_ asks the server to play * _move:_ gives a client move @@ -75,12 +80,14 @@ This plugin provides an interactive Tic Tac Toe game where the binder returns th ### Audio A sample Audio plugin with 2 backends: - * ALSA (mandatory) - * PulseAudio (optional) + +* ALSA (mandatory) +* PulseAudio (optional) This plugin is able to initialize a specific soundcard, define volume levels, channels (mono/stereo...), mute sound, and play a 22,050 Hz PCM stream. **Verbs**: + * _ping:_ returns a success response * _init:_ initializes backend, on the "default" sound card * _volume:_ gets or sets volume, in % (0-100) @@ -100,11 +107,13 @@ _(a specifc backend can be forced by using this syntax before running afb-daemon ### Radio A sample AM/FM Radio plugin with 1 backend: - * RTLSDR - Realtek RTL2832U dongles (mandatory) + +* RTLSDR - Realtek RTL2832U dongles (mandatory) This plugin is able to initialize specific RTL2832U dongles, switch between AM/FM modes, define frequency, mute sound, and play sound (if combining with the **audio** plugin). **Verbs**: + * _ping:_ returns a success response * _init:_ initializes backend, looking for plugged-in devices * _power:_ sets device power status (on-off) @@ -121,11 +130,13 @@ _(if rtlsdr development libraries are not found at build time, this plugin will ### Media A sample Media Server plugin with 1 backend: + * Rygel This plugin is able to detect a local Rygel UPnP media server, list audio files, select an audio file for playback, play/pause/seek in this file, upload an audio file to the server. **Verbs**: + * _ping:_ returns a success response * _init:_ initializes backend, looking for an active local UPnP server * _list:_ returns list of audio files, as a JSON structure diff --git a/doc/afb-tests-overview.html b/doc/afb-tests-overview.html index f5dcb646..ce1cba44 100644 --- a/doc/afb-tests-overview.html +++ b/doc/afb-tests-overview.html @@ -18,9 +18,9 @@ Author: Manuel Bachmann

    Here are the tests shipped in the source tree:

    @@ -52,7 +52,7 @@ Author: Manuel Bachmann So, try:

    auth connect
-audio init
+hello pingjson true


    diff --git a/doc/afb-tests-overview.md b/doc/afb-tests-overview.md index 4ea25275..98d971fc 100644 --- a/doc/afb-tests-overview.md +++ b/doc/afb-tests-overview.md @@ -9,7 +9,9 @@ Here are the tests shipped in the source tree: * **afb-client-demo** (command-line WebSockets) + * **token-websock.qml** (Qt/QML WebSockets) + * ***.html** (HTML5/JS HTTP-REST & WebSockets) @@ -38,7 +40,7 @@ The command doesn't return. You should type requests of type [ -- 2.16.6