migrate config to use the mkdocs material custom style templates. expand content.

amqtt/contrib/http.py

@@ -137,46 +137,27 @@ class HttpAuthPlugin(BaseAuthPlugin, BaseTopicPlugin):
 
     @dataclass
     class Config:
-        """Configuration for the HTTP Auth & ACL Plugin.
+        """Configuration for the HTTP Auth & ACL Plugin."""
-
-        Members:
-            - host *(str) hostname of the server for the auth & acl check
-            - port *(int) port of the server for the auth & acl check
-            - user_uri *(str) uri of the topic check (e.g. '/user')
-            - topic_uri *(str) uri of the topic check (e.g. '/acl')
-            - request_method *(RequestMethod) send the request as a GET, POST or PUT
-            - params_mode *(ParamsMode) send the request with json or form data
-            - response_mode *(ResponseMode) expected response from the auth/acl server. STATUS (code), JSON, or TEXT.
-            - user_agent *(str) the 'User-Agent' header sent along with the request
-
-        ParamsMode:
-
-        for user authentication, the http server will receive in json or form format the following:
-            - username *(str)*
-            - password *(str)*
-            - client_id *(str)*
-
-        for superuser validation, the http server will receive in json or form format the following:
-            - username *(str)*
-
-        for acl check, the http server will receive in json or form format the following:
-            - username *(str)*
-            - client_id *(str)*
-            - topic *(str)*
-            - acc *(int)* client can receive (1), can publish(2), can receive & publish (3) and can subscribe (4)
-        """
 
         host: str
         """hostname of the server for the auth & acl check"""
         port: int
         """port of the server for the auth & acl check"""
         user_uri: str
+        """URI of the topic check (e.g. '/user')"""
         topic_uri: str
+        """URI of the topic check (e.g. '/acl')"""
         request_method: RequestMethod = RequestMethod.GET
-        params_mode: ParamsMode = ParamsMode.JSON
+        """send the request as a GET, POST or PUT"""
-        response_mode: ResponseMode = ResponseMode.JSON
+        params_mode: ParamsMode = ParamsMode.JSON  # see docs/plugins/http.md for additional details
+        """send the request with `JSON` or `FORM` data. *additional details below*"""
+        response_mode: ResponseMode = ResponseMode.JSON  # see docs/plugins/http.md for additional details
+        """expected response from the auth/acl server. `STATUS` (code), `JSON`, or `TEXT`. *additional details below*"""
         with_tls: bool = False
+        """http or https"""
         user_agent: str = "amqtt"
-
+        """the 'User-Agent' header sent along with the request"""
         superuser_uri: str | None = None
+        """URI to verify if the user is a superuser (e.g. '/superuser'), `None` if superuser is not supported"""
         timeout: int = 5
+        """duration, in seconds, to wait for the HTTP server to respond"""

docs/plugins/http.md

@@ -1,49 +1,97 @@
-# Authentication & Topic Access via external HTTP server
+# Authentication & Authorization via external HTTP server
 
-`amqtt.contrib.http.HttpAuthTopicPlugin`
+`amqtt.contrib.http.HttpAuthPlugin`
 
-If clients accessing the broker are managed by another application, implement API endpoints
+If clients accessing the broker are managed by another application, it can implement API endpoints
-that allows the broker to check if a client is authenticated and what topics that client
+that respond with information about client authenticated and topic-level authorization.
-is authorized to access.
+
+!!! info "browser-based mqtt over websockets"
+
+    One of the primary use cases for this plugin is to enable browser-based applications to communicate with mqtt
+    over websockets.
+
+    !!! warning
+        Care must be taken to make sure the mqtt password is secure (encrypted).
+    
+    For more implementation information:
+
+    ??? info "recipe for authentication"
+        Provide the client id and username when webpage is initially rendered or passed to the mqtt initialization from stored
+         cookies. If application is secure, the user's password will be hashed should be encrypted and cannot be used to 
+         authenticate a client. Instead, the application should create an encrypted password (eg jwt) which the server
+         can then verify when the broker contacts the application.
+
+    ??? example "mqtt in javascript"
+          Example initialization of mqtt in javascript:
+
+            import mqtt from 'mqtt';
+            const url = 'https://path.to.amqtt.broker';
+            const options = {
+              'myclientid',
+              connectTimeout: 30000,
+              username: 'myclientid',
+              password: ''  // encrypted password
+            };
+            try {
+              const clientMqtt = await mqtt.connect(url, options);
+
+See the 'Request and Response Modes' section below for details on `params_mode` and `response_mode`. 
 
 ::: amqtt.contrib.http.HttpAuthPlugin.Config
     options:
       show_source: false
       heading_level: 4
+      extra:
+        class_style: "simple"
 
-**Configuration**
+[//]: # (manually creating the heading so it doesn't show in the sidebar ToC)
+<h2>Params and Response Modes</h2>
 
-- `host` *(str) hostname of the server for the auth & acl check
+Each URI endpoint will receive different information in order to determine authentication and authorization;
-- `port` *(int) port of the server for the auth & acl check
+format will depend on `params_mode` configuration attribute (`json` or `form`).:
-- `user_uri` *(str) uri of the user auth check (e.g. '/user')
-- `topic_uri` *(str) uri of the topic check (e.g. '/acl')
-- `request_method` *(RequestMethod) send the request as a GET, POST or PUT
-- `params_mode` *(ParamsMode) send the request with json or form data
-- `response_mode` *(ResponseMode) expected response from the auth/acl server. STATUS (code), JSON, or TEXT.
-- `user_agent` *(str) the 'User-Agent' header sent along with the request
 
-Each endpoint (uri) will receive the information needed to determine authentication and authorization (in either
+*For user authentication, the request will contain:*
-json or form data format, based on the `params_mode`)
 
-For user authentication (`user_uri`), the http server will receive in json or form format the following:
     - username *(str)*
     - password *(str)*
     - client_id *(str)*
 
-For superuser validation (`superuser_uri`), the http server will receive in json or form format the following:
+*For superuser validation, the request will contain:*
+
     - username *(str)*
 
-For acl check (`acl_uri`), the http server will receive in json or form format the following:
+*For acl check, the request will contain:*
+
     - username *(str)*
     - client_id *(str)*
     - topic *(str)*
-    - acc *(int)* client can receive (1), can publish(2), can receive & publish (3) and can subscribe (4)
+    - acc *(int)* : client can receive (1), can publish(2), can receive & publish (3) and can subscribe (4)
 
+All endpoints should respond with the following, dependent on `response_mode` configuration attribute:
 
-The HTTP endpoints can respond in three different ways, depending on `response_mode`:
+*In `status` mode:
 
-1. STATUS - allowing access should respond with a 2xx status code. rejection is 4xx. 
+    - status code: 2xx (granted) or 4xx(denied) or 5xx (noop)
-    if a 5xx is received, the plugin will not participate in the filtering operation and will defer to another topic filtering plugin to determine access
+
-2. JSON - response should be `{'ok':true|false|null, 'error':'optional reason for false or null response'}`.
+!!! note "5xx response"
-   `true` allows access, `false` denies access and `null` the plugin will not participate in the filtering operation
+    **noop** (no operation): plugin will not participate in the filtering operation and will defer to another
-3. TEXT - `ok` allows access, any other message denies access. non-participation not supported with this mode.
+    topic filtering plugin to determine access. if there is no other topic filtering plugin, access will be denied.
+
+*In `json` mode:*
+
+    - status code: 2xx
+    - content-type: application/json
+    - response: {'ok': True } (granted), {'ok': False, 'error': 'optional error message' } (denied) or { 'error': 'optional error message' } (noop)
+
+!!! note "excluded 'ok' key"
+    **noop** (no operation): plugin will not participate in the filtering operation and will defer to another
+     topic filtering plugin to determine access. if there is no other topic filtering plugin, access will be denied.
+
+*In `text` mode:*
+
+    - status code: 2xx
+    - content-type: text/plain
+    - response: 'ok' or 'error'
+
+!!! note "noop not supported"
+    in text mode, noop (no operation) is not supported