GitHubProjectStore#
- class gafaelfawr.storage.github_project.GitHubProjectStore(session)#
Bases:
objectStores and retrieves registered GitHub projects.
The store performs no validation beyond what the database enforces. The rules of the registry, such as deriving the bot username, pinning the repository IDs, and refusing overlapping projects, are the responsibility of the service.
- Parameters:
session (
AsyncSession) – The database session proxy.
Methods Summary
add(create, *, username, repository, ...[, ...])Store a new GitHub project.
delete(project_id)Delete a GitHub project.
get(project_id)Retrieve a GitHub project.
list(*[, repository, username, template, ...])List GitHub projects.
lock()Take the lock serializing writes to the registry.
update(project_id, update, *, username, ...)Modify a GitHub project.
Methods Documentation
- async add(create, *, username, repository, max_lifetime, created_by, template=None)#
Store a new GitHub project.
- Parameters:
create (
GitHubProjectCreate) – Fields of the new project.username (
str) – Bot username of the project, either as given or as derived from the repository.repository (
GitHubRepository) – Repository metadata from GitHub, used for the canonical name of the repository and its pinned IDs.max_lifetime (
timedelta) – Maximum lifetime of tokens minted for the project, either as given or as defaulted by the service.created_by (
str) – Username of the person creating the project.template (
str|None, default:None) – Name of the project template the project was provisioned from, if any.
- Returns:
The stored project, including its assigned ID.
- Return type:
- async delete(project_id)#
Delete a GitHub project.
- async get(project_id)#
Retrieve a GitHub project.
- async list(*, repository=None, username=None, template=None, requested_by=None)#
List GitHub projects.
- Parameters:
repository (
str|None, default:None) – Limit the results to projects for this repository, compared case-insensitively.username (
str|None, default:None) – Limit the results to projects for this bot username.template (
str|None, default:None) – Limit the results to projects provisioned from this template.requested_by (
str|None, default:None) – Limit the results to projects requested by this identifier.
- Returns:
Matching projects, ordered by ID.
- Return type:
- async lock()#
Take the lock serializing writes to the registry.
The registry has invariants that span rows, such as at most one enabled project matching a given token, a derived username belonging to a single repository, and no project naming a deleted template, which the service checks by reading the registry before writing to it. Holding this lock across the check and the write makes those read-then-write sequences atomic: a concurrent writer blocks here until this transaction commits or rolls back, and then sees its rows. The lock covers project templates as well as projects, since provisioning reads a template and writes a project.
Must be called from inside a transaction. The lock is scoped to that transaction and is released automatically when it ends, so there is no corresponding unlock.
Notes
This is a single lock for the whole registry rather than one per repository or per username. The invariants cross those boundaries (a derived username ties together different repositories), so finer-grained locks would need to be taken in a fixed order to avoid deadlocks. Registry writes are rare administrative actions, so serializing all of them costs nothing noticeable and keeps the reasoning simple.
The lock is a PostgreSQL transaction-scoped advisory lock. If there is ever a need to support a database without advisory locks, fallback code (probably locking a dedicated row) will need to be added here.
- Return type:
- async update(project_id, update, *, username, repository, modified, modified_by)#
Modify a GitHub project.
Only the fields set in the update are changed. The username and repository are taken from the separate arguments rather than from the update, since the service resolves them. Each field is assigned explicitly, so a new field of the project must be added here as well as to
add.- Parameters:
project_id (
int) – ID of the project.update (
GitHubProjectUpdate) – Changes to apply.username (
str|None) – New bot username of the project, either as given or as derived from the repository, orNoneto leave it unchanged.repository (
GitHubRepository|None) – Repository metadata from GitHub if the repository is changing, used for the canonical name of the repository and its pinned IDs, orNoneto leave the repository unchanged.modified (
datetime) – Time of the change.modified_by (
str) – Username of the person making the change.
- Returns:
- Return type: