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 <[email protected]>
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: [email protected]
For additional commands, e-mail: [email protected]
