📝 — Document how to add data to requests (fix #77)

CHANGELOG.md

@@ -2,11 +2,20 @@
 
 ## [Unreleased]
 
+- ✨ — Allow to customize agent User-Agent header (#78)
+- 📝 — Document how to add data to requests (#77)
+
+## 0.7.4
+
+Date: 2025-02-12
+
+- 🐛 — Fix method enum in tasks table (thx to Dryusdan)
+
 ## 0.7.3
 
 Date: 2025-01-26
 
-🐛 — Fix bug in retry_before_notification logic when success
+- 🐛 — Fix bug in retry_before_notification logic when success
 
 ## 0.7.2
 

argos/__init__.py

@@ -1 +1 @@
-VERSION = "0.7.3"
+VERSION = "0.7.4"

argos/agent.py

@@ -37,11 +37,17 @@ def log_failure(retry_state):
 class ArgosAgent:  # pylint: disable-msg=too-many-instance-attributes
     """The Argos agent is responsible for running the checks and reporting the results."""
 
-    def __init__(self, server: str, auth: str, max_tasks: int, wait_time: int):
+    def __init__(  # pylint: disable-msg=too-many-positional-arguments
+        self, server: str, auth: str, max_tasks: int, wait_time: int, user_agent: str
+    ):
         self.server = server
         self.max_tasks = max_tasks
         self.wait_time = wait_time
         self.auth = auth
+        if user_agent == "":
+            self.ua = user_agent
+        else:
+            self.ua = f" - {user_agent}"
         self._http_client: httpx.AsyncClient | None = None
         self._http_client_v4: httpx.AsyncClient | None = None
         self._http_client_v6: httpx.AsyncClient | None = None
@@ -53,13 +59,13 @@ class ArgosAgent:  # pylint: disable-msg=too-many-instance-attributes
     async def run(self):
         auth_header = {
             "Authorization": f"Bearer {self.auth}",
-            "User-Agent": f"Argos Panoptes agent {VERSION}",
+            "User-Agent": f"Argos Panoptes agent {VERSION}{self.ua}",
         }
         self._http_client = httpx.AsyncClient(headers=auth_header)
 
         ua_header = {
             "User-Agent": f"Argos Panoptes {VERSION} "
-            "(about: https://argos-monitoring.framasoft.org/)",
+            f"(about: https://argos-monitoring.framasoft.org/){self.ua}",
         }
         self._http_client_v4 = httpx.AsyncClient(
             headers=ua_header,

argos/commands.py

@@ -92,7 +92,12 @@ def version():
     default="INFO",
     type=click.Choice(logging.LOG_LEVELS, case_sensitive=False),
 )
-def agent(server_url, auth, max_tasks, wait_time, log_level):
+@click.option(
+    "--user-agent",
+    default="",
+    help="A custom string to append to the User-Agent header",
+)
+def agent(server_url, auth, max_tasks, wait_time, log_level, user_agent):  # pylint: disable-msg=too-many-positional-arguments
     """Get and run tasks for the provided server. Will wait for new tasks.
 
     Usage: argos agent https://argos.example.org "auth-token-here"
@@ -108,7 +113,7 @@ def agent(server_url, auth, max_tasks, wait_time, log_level):
     from argos.logging import logger
 
     logger.setLevel(log_level)
-    agent_ = ArgosAgent(server_url, auth, max_tasks, wait_time)
+    agent_ = ArgosAgent(server_url, auth, max_tasks, wait_time, user_agent)
     asyncio.run(agent_.run())
 
 

argos/server/migrations/versions/dcf73fa19fce_specify_check_method.py

@@ -5,6 +5,7 @@ Revises: c780864dc407
 Create Date: 2024-11-26 14:40:27.510587
 
 """
+
 from typing import Sequence, Union
 
 from alembic import op
@@ -19,22 +20,25 @@ depends_on: Union[str, Sequence[str], None] = None
 
 
 def upgrade() -> None:
+    enum = sa.Enum(
+        "GET",
+        "HEAD",
+        "POST",
+        "OPTIONS",
+        "CONNECT",
+        "TRACE",
+        "PUT",
+        "PATCH",
+        "DELETE",
+        name="method",
+        create_type=False,
+    )
+    enum.create(op.get_bind(), checkfirst=True)
     with op.batch_alter_table("tasks", schema=None) as batch_op:
         batch_op.add_column(
             sa.Column(
                 "method",
-                sa.Enum(
-                    "GET",
-                    "HEAD",
-                    "POST",
-                    "OPTIONS",
-                    "CONNECT",
-                    "TRACE",
-                    "PUT",
-                    "PATCH",
-                    "DELETE",
-                    name="method",
-                ),
+                enum,
                 nullable=False,
                 server_default="GET",
             )
@@ -44,3 +48,4 @@ def upgrade() -> None:
 def downgrade() -> None:
     with op.batch_alter_table("tasks", schema=None) as batch_op:
         batch_op.drop_column("method")
+        sa.Enum(name="method").drop(op.get_bind(), checkfirst=True)

docs/checks.md

@@ -82,6 +82,48 @@ caption: argos-config.yaml
         - json-is: '{"foo": "bar", "baz": 42}'
 ```
 
+## Add data to requests
+
+If you want to specify query parameters, just put them in the path:
+
+```{code-block} yaml
+websites:
+  - domain: "https://contact.example.org"
+    paths:
+      - path: "/index.php?action=show_messages"
+        method: "GET"
+```
+
+If you want, for example, to test a form and send some data to it:
+
+```{code-block} yaml
+websites:
+  - domain: "https://contact.example.org"
+    paths:
+      - path: "/"
+        method: "POST"
+        request_data:
+          # These are the data sent to the server: title and msg
+          data:
+            title: "Hello my friend"
+            msg: "How are you today?"
+          # To send data as JSON (optional, default is false):
+          is_json: true
+```
+
+If you need to send some headers in the request:
+
+```{code-block} yaml
+websites:
+  - domain: "https://contact.example.org"
+    paths:
+      - path: "/api/mail"
+        method: "PUT"
+        request_data:
+          headers:
+            Authorization: "Bearer foo-bar-baz"
+```
+
 ## SSL certificate expiration
 
  Checks that the SSL certificate will not expire soon. You need to define the thresholds in the configuration, and set the `on-check` option to enable the check.

docs/cli.md

@@ -61,6 +61,8 @@ Options:
   --wait-time INTEGER             Waiting time between two polls on the server
                                   (seconds)
   --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
+  --user-agent TEXT               A custom string to append to the User-Agent
+                                  header
   --help                          Show this message and exit.
 ```