Metadata-Version: 2.4
Name: fastapi-lro
Version: 0.0.1
Summary: fastapi with support of long running operations
Author-email: Macoyshev <make.oynoshev@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: arq>=0.26.3
Requires-Dist: fastapi>=0.121.0
Requires-Dist: mcp>=1.21.0
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: uvicorn>=0.38.0
Dynamic: license-file

# FastAPI-LRO

[![CI](https://github.com/macoyshev/fastapi-lro/actions/workflows/ci.yaml/badge.svg)](
https://github.com/macoyshev/fastapi-lro/actions/workflows/ci.yml
)

**FastAPI-LRO** is a **drop-in replacement for FastAPI** that automatically turns all endpoints into **long-running asynchronous tasks**.

Instead of blocking request/response cycles, every endpoint execution is converted into a background job handled by workers, with built-in job management APIs.

## Key Ideas

- Every endpoint runs as an **async job by default**
- Requests return a **job ID immediately**
- Results are fetched via provided job endpoints
- Optional endpoint to **block until job completion**
- Scales horizontally by spawning **multiple workers**
- Uses **Redis** as the job backend

## Features

- Drop-in FastAPI replacement
- Automatic LRO behavior for all endpoints
- Default job management endpoints
- Blocking and non-blocking result retrieval
- Multiple worker support
- Redis-backed job storage
- Minimal configuration

## Default Behavior

All endpoints are treated as **long-running operations** automatically.

To **disable LRO for a specific endpoint**, pass the `not_lro` parameter to the decorator:

```python
@app.get("/health", not_lro=True)
def health():
    return {"status": "ok"}
```


## Job Endpoints

FastAPI-LRO provides default endpoints to manage jobs:

- Get job result
- Get job status
- Block until job completion

These endpoints allow clients to poll or wait synchronously for results without blocking workers.

## Running the API

Start the API normally (same as FastAPI):

```bash
uvicorn fastapi_lro.main:app --reload
```

## Running Workers

Workers execute the background jobs.

```bash
python -m fastapi_lro <app_location>:<app_name> --worker
```

Example:

```bash
python -m fastapi_lro <app_location>:<app_name> --worker
```

You can spawn multiple workers to scale processing:

```bash
python -m fastapi_lro app.main:app --worker
python -m fastapi_lro app.main:app --worker
```

## Redis Configuration

FastAPI-LRO requires Redis.
Configure Redis via environment variables:

```bash
export REDIS_HOST=0.0.0.0
export REDIS_PORT=6379
```

Defaults:

- redis_host = 0.0.0.0
- redis_port = 6379

## Typical Flow

1. Client calls an API endpoint
2. Server immediately returns a job ID
3. Worker processes the task asynchronously
4. Client fetches the result or blocks until completion

## Use Cases

- Long computations
- IO-heavy operations
- External API calls
- Background processing
- Task queues without extra frameworks


## Local development

The project includes a `Makefile` to simplify common development tasks.

### Available Commands

#### Run tests

Runs the full pytest test suite including async tests and coverage:
```bash
make test
```

#### Format code
Automatically formats the codebase using the configured formatter:

```bash
make format
```

#### Build the package
Build the package for distribution:
```bash
make build
```


