Metadata-Version: 2.4
Name: perfact-api-main
Version: 0.9
Summary: PerFact API - FastAPI main package (middleware, auth, entrypoints)
Author-email: Viktor Dick <viktor.dick@perfact.de>
License: GPL-2.0-or-later
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: SQL
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: argon2-cffi
Requires-Dist: psycopg[binary]
Requires-Dist: fastapi[standard-no-fastapi-cloud-cli]
Requires-Dist: sqlalchemy
Requires-Dist: pydantic-settings
Requires-Dist: perfact-api-app

# PerFact API Base
The main FastAPI package for the PerFact API. Provides authentication, authorisation, database session handling, and plugin discovery. All domain-specific API modules are in separate packages and loaded automatically at startup via entry points.

## Applications

### `perfact.api.main.app` — user-facing API

Hosts all plugins registered under the `perfact.api` entry point group. All routes are served under the `/api` path prefix. Users authenticate via a login cookie or an `Authorization: Apikey …` header. Access to individual endpoints can be restricted by role:

```python
from perfact.api.main.auth import require_roles

@router.get("/my-endpoint")
@require_roles("MyRole")
def my_endpoint(session: DBSession) -> ...:
    ...
```

### `perfact.api.main.assignworker` — task runner API

Hosts all plugins registered under the `perfact.assignapi` entry point group. All routes are served under the `/assignworker` path prefix. Intended for internal use by `assignd`. Authentication is HTTP Basic Auth with a pre-shared password hash configured in the YAML config file.

## Plugin discovery

At startup, both apps iterate over their respective entry point group and call `mount(app)` on each discovered plugin:

```
INFO - start plugin discovery
INFO - try to include plugin: perfact.api.pd.routes:mount
INFO - finished discovery and include: 1 plugins
```

A plugin registers itself by declaring an entry point in its `pyproject.toml`:

```toml
[project.entry-points.'perfact.api']
myplugin = 'perfact.api.myplugin.routes:mount'
```

## getting started as developer
After you checked out this repository, do the following steps to be able to debug your application:
1. create and activate *venv*
    ```sh
    python -m venv .venv

    source .venv/bin/activate # linux
    .venv/Scripts/Activate.ps1 # PowerShell
    ```
1. Install the API plugins you want to include without doing changes by installing them from pypi:
    ```sh
    pip install perfact-api-base
    ```
1. Install the API plugins you want to include and **change** in your instance by checking them out somewhere and installing/linking them into your application via `pip install -e`:
    ```sh
    pip install -e ../perfact-api-base/ # required
    pip install -e ../perfact-api-app/app/ # required
    pip install -e ../perfact-api-pd-model/ # example
    ```

**Hint**: Every code change is available in the application after the next restart/reload. Changes to the entrypoints are available after the next install command execution (as this is recreating the `ENTRYPOINTS`-file belonging to the package in the site-packages folder).

You can install as much as plugins you like, even custom ones.

*pip* will automaticly check if more dependencies needed by the plugin while installing, e.g.
```
Requirement already satisfied: fastapi
```


Now you can run the application:
```
uvicorn perfact.api.main.app:app # run API for frontend
uvicorn perfact.api.main.assignworker:app # run API for assignd worker APIs
uvicorn perfact.api.main.app:app  --reload --reload-include ../ # run API for frontend with auto-reload for all editable dependencies
```

There is a `launch.json`-file provided to debug the application in VS Code. To use that, you have to create a configuration file (see below).

## Configuration
The application can be configured by providing a configuration yaml-File containing informations about the database connection and basic auth credentials (for `assignworker`).
The configuration file is given to the application by providing the location (absolute or relative to working dir) in the environment variable `PERFACT_API_CONFIG_PATH`.

Example:
```yaml
connstr: postgresql+psycopg://zope@/perfactema # default, can be left out
basicauth: "$argon2id$v=19$m=65536,t=3,p=4$6itEouPTNwWEXDKScKmMrw$NwhN1vAUN8EZjC62HrtXjx7n+K1Mujjd/QqioaHvyOg" # password=test
```

## Dependencies
- `perfact-api-app`
- `fastapi`
- `sqlalchemy`
- `psycopg[c]`
- `argon2-cffi`
- `pydantic-settings`

## Maintainers
- Viktor Dick <viktor.dick@perfact.de>
- Alexander Rolfes <alexander.rolfes@perfact.de>
