You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by sb...@apache.org on 2025/10/08 18:54:22 UTC

(tooling-trusted-releases) branch main updated: Add authentication and API sections to the documentation

This is an automated email from the ASF dual-hosted git repository.

sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git


The following commit(s) were added to refs/heads/main by this push:
     new 504a69b  Add authentication and API sections to the documentation
504a69b is described below

commit 504a69b93078f9662a9524d941628b4e951d2ad0
Author: Sean B. Palmer <se...@miscoranda.com>
AuthorDate: Wed Oct 8 19:54:03 2025 +0100

    Add authentication and API sections to the documentation
---
 atr/docs/developer-guide.html     |  9 +++++++--
 atr/docs/developer-guide.md       | 11 +++++++++++
 atr/docs/introduction-to-atr.html |  4 ++--
 atr/docs/introduction-to-atr.md   |  1 +
 4 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/atr/docs/developer-guide.html b/atr/docs/developer-guide.html
index 18cdead..dc1c045 100644
--- a/atr/docs/developer-guide.html
+++ b/atr/docs/developer-guide.html
@@ -1,6 +1,6 @@
 <h1 id="developer-guide">2. Developer guide</h1>
-<p><strong>Up</strong>: <a href=".">Apache Trusted Releases documentation</a>
-<strong>Prev</strong>: 1. <a href="introduction-to-atr">Introduction to ATR</a></p>
+<p><strong>Up</strong>: <a href=".">Apache Trusted Releases documentation</a></p>
+<p><strong>Prev</strong>: 1. <a href="introduction-to-atr">Introduction to ATR</a></p>
 <p>This is a guide for developers of ATR, explaining how to make changes to the ATR source code. For more information about how to contribute those changes back to us, please read the <a href="contribution-guide">contribution guide</a> instead.</p>
 <h2 id="running-the-server">Running the server</h2>
 <p>To develop ATR locally, we manage dependencies using <a href="https://docs.astral.sh/uv/">uv</a>. To run ATR on ASF hardware, we run it in containers managed by Puppet, but since this guide is about development, we focus on using uv.</p>
@@ -61,5 +61,10 @@ make serve-local
 <p>The ATR <a href="/ref/atr/manager.py"><code>manager</code></a> module provides the <a href="/ref/atr/manager.py:WorkerManager"><code>WorkerManager</code></a> class, which maintains a pool of worker processes. When the ATR server starts, the manager spawns a configurable number of worker processes and monitors them continuously. The manager checks every few seconds whether workers are still running, whether any tasks have exceeded their time limits, and whether the worker pool needs to [...]
 <p>The ATR <a href="/ref/atr/worker.py"><code>worker</code></a> module implements the workers. Each worker process runs in a loop. It claims the oldest queued task from the database, executes it, records the result, and then claims the next task atomically using an <code>UPDATE ... WHERE</code> statement. After a worker has processed a fixed number of tasks, it exits voluntarily to help to avoid memory leaks. The manager then spawns a fresh worker to replace it. Task execution happens in [...]
 <p>Tasks themselves are defined in the ATR <a href="/ref/atr/tasks/"><code>tasks</code></a> directory. The <a href="/ref/atr/tasks/__init__.py"><code>tasks</code></a> module contains functions for queueing tasks and resolving task types to their handler functions. Task types include operations such as importing keys, generating SBOMs, sending messages, and importing files from SVN. The most common category of task is automated checks on release artifacts. These checks are implemented in  [...]
+<h3 id="authentication">Authentication</h3>
+<p>ATR uses ASF OAuth for user login, and then determines what actions each user can perform based on their committee memberships. The ATR <a href="/ref/atr/principal.py"><code>principal</code></a> module handles authorization by checking whether users are members of relevant committees. It queries and caches LDAP to get committee membership information. The <a href="/ref/atr/principal.py:Authorisation"><code>Authorisation</code></a> class provides methods to check whether a user is a me [...]
+<h3 id="api">API</h3>
+<p>The ATR API provides programmatic access to most ATR functionality. API endpoints are defined in <a href="/ref/atr/blueprints/api/api.py"><code>blueprints.api.api</code></a>, and their URL paths are prefixed with <code>/api/</code>. The API uses <a href="https://www.openapis.org/">OpenAPI</a> for documentation, which is automatically generated from the endpoint definitions and served at <code>/api/docs</code>. Users send requests with a <a href="https://en.wikipedia.org/wiki/JSON_Web_ [...]
+<p>API request and response models are defined in <a href="/ref/atr/models/api.py"><code>models.api</code></a> using Pydantic. Each endpoint has an associated request model that validates incoming data, and a response model that validates outgoing data. The API returns JSON in all cases, with appropriate HTTP status codes.</p>
 <h3 id="other-important-interfaces">Other important interfaces</h3>
 <p>The server configuration in <a href="/ref/atr/config.py"><code>config</code></a> determines a lot of global state, and the <a href="/ref/atr/util.py"><code>util</code></a> module contains lots of useful code which is used throughout ATR.</p>
diff --git a/atr/docs/developer-guide.md b/atr/docs/developer-guide.md
index c57023c..a6dd653 100644
--- a/atr/docs/developer-guide.md
+++ b/atr/docs/developer-guide.md
@@ -1,6 +1,7 @@
 # 2. Developer guide
 
 **Up**: [Apache Trusted Releases documentation](.)
+
 **Prev**: 1. [Introduction to ATR](introduction-to-atr)
 
 This is a guide for developers of ATR, explaining how to make changes to the ATR source code. For more information about how to contribute those changes back to us, please read the [contribution guide](contribution-guide) instead.
@@ -111,6 +112,16 @@ The ATR [`worker`](/ref/atr/worker.py) module implements the workers. Each worke
 
 Tasks themselves are defined in the ATR [`tasks`](/ref/atr/tasks/) directory. The [`tasks`](/ref/atr/tasks/__init__.py) module contains functions for queueing tasks and resolving task types to their handler functions. Task types include operations such as importing keys, generating SBOMs, sending messages, and importing files from SVN. The most common category of task is automated checks on release artifacts. These checks are implemented in [`tasks/checks/`](/ref/atr/tasks/checks/), and  [...]
 
+### Authentication
+
+ATR uses ASF OAuth for user login, and then determines what actions each user can perform based on their committee memberships. The ATR [`principal`](/ref/atr/principal.py) module handles authorization by checking whether users are members of relevant committees. It queries and caches LDAP to get committee membership information. The [`Authorisation`](/ref/atr/principal.py:Authorisation) class provides methods to check whether a user is a member of a committee or a project participant, w [...]
+
+### API
+
+The ATR API provides programmatic access to most ATR functionality. API endpoints are defined in [`blueprints.api.api`](/ref/atr/blueprints/api/api.py), and their URL paths are prefixed with `/api/`. The API uses [OpenAPI](https://www.openapis.org/) for documentation, which is automatically generated from the endpoint definitions and served at `/api/docs`. Users send requests with a [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) created from a [PAT](https://en.wikipedia.org/wiki/Per [...]
+
+API request and response models are defined in [`models.api`](/ref/atr/models/api.py) using Pydantic. Each endpoint has an associated request model that validates incoming data, and a response model that validates outgoing data. The API returns JSON in all cases, with appropriate HTTP status codes.
+
 ### Other important interfaces
 
 The server configuration in [`config`](/ref/atr/config.py) determines a lot of global state, and the [`util`](/ref/atr/util.py) module contains lots of useful code which is used throughout ATR.
diff --git a/atr/docs/introduction-to-atr.html b/atr/docs/introduction-to-atr.html
index 7c7761b..3a98507 100644
--- a/atr/docs/introduction-to-atr.html
+++ b/atr/docs/introduction-to-atr.html
@@ -1,6 +1,6 @@
 <h1 id="introduction-to-atr">1. Introduction to ATR</h1>
-<p><strong>Up</strong>: <a href=".">Apache Trusted Releases documentation</a>
-<strong>Next</strong>: 2. <a href="developer-guide">Developer guide</a></p>
+<p><strong>Up</strong>: <a href=".">Apache Trusted Releases documentation</a></p>
+<p><strong>Next</strong>: 2. <a href="developer-guide">Developer guide</a></p>
 <ul>
 <li><a href="#what-is-atr">What is ATR?</a></li>
 <li><a href="#who-are-atr-users">Who are ATR users?</a></li>
diff --git a/atr/docs/introduction-to-atr.md b/atr/docs/introduction-to-atr.md
index 594dcd3..f39eecd 100644
--- a/atr/docs/introduction-to-atr.md
+++ b/atr/docs/introduction-to-atr.md
@@ -1,6 +1,7 @@
 # 1. Introduction to ATR
 
 **Up**: [Apache Trusted Releases documentation](.)
+
 **Next**: 2. [Developer guide](developer-guide)
 
 * [What is ATR?](#what-is-atr)


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org