pg-api 0.1.0

# pg-api

[![Crates.io](https://img.shields.io/crates/v/pg-api.svg)](https://crates.io/crates/pg-api)
[![Documentation](https://docs.rs/pg-api/badge.svg)](https://docs.rs/pg-api)
[![GitLab CI](https://gitlab.com/alexandre/pg-api/badges/main/pipeline.svg)](https://gitlab.com/alexandre/pg-api/-/pipelines)
[![License](https://img.shields.io/crates/l/pg-api.svg)](https://gitlab.com/alexandre/pg-api/blob/main/LICENSE)

A high-performance PostgreSQL REST API driver built with Rust, featuring rate limiting, connection pooling, and comprehensive observability.

## Features

- **High Performance**: Built with Rust and Axum for maximum throughput
- **Connection Pooling**: Efficient database connection management with deadpool-postgres
- **Rate Limiting**: Configurable per-account rate limits with sliding window algorithm
- **Multi-tenancy**: Support for multiple accounts with isolated configurations
- **Observability**: Built-in metrics, tracing, and optional OpenSearch integration
- **Security**: API token authentication, query timeouts, and audit logging
- **License Management**: Flexible offline/online license validation system
- **Production Ready**: SystemD integration, health checks, and graceful shutdown

## Installation

### From Source

```bash
# Clone the repository
git clone https://gitlab.com/alexandre/pg-api.git
cd pg-api

# Build in release mode
cargo build --release

# Run the binary
./target/release/pg-api
```

### Using Cargo

```bash
cargo install pg-api
```

## Configuration

The API uses JSON configuration files located in the `config/` directory:

### Server Configuration (`config/server.json`)

```json
{
  "host": "127.0.0.1",
  "port": 8580,
  "max_connections": 100,
  "timeout_seconds": 30,
  "log_level": "info"
}
```

### Account Configuration (`config/accounts.json`)

```json
[
  {
    "id": "acc_example",
    "name": "Example Account",
    "api_token": "sk_live_example_token",
    "database_url": "postgresql://user:pass@localhost/dbname",
    "rate_limit": 100,
    "max_connections": 10,
    "allowed_operations": ["SELECT", "INSERT", "UPDATE", "DELETE"]
  }
]
```

## API Usage

### Authentication

All requests require an API token in the Authorization header:

```bash
curl -H "Authorization: Bearer sk_live_your_token" \
     https://api.example.com/v1/query
```

### Query Execution

```bash
curl -X POST https://api.example.com/v1/query \
  -H "Authorization: Bearer sk_live_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE active = $1",
    "params": [true],
    "database": "main"
  }'
```

### Health Check

```bash
curl https://api.example.com/health
```

### Account Information

```bash
curl -H "Authorization: Bearer sk_live_your_token" \
     https://api.example.com/v1/account
```

## Development

### Prerequisites

- Rust 1.75 or higher
- PostgreSQL 12 or higher
- Optional: OpenSearch for observability

### Running Tests

```bash
cargo test
```

### Running with Hot Reload

```bash
cargo watch -x run
```

### Linting

```bash
cargo clippy -- -D warnings
```

### Formatting

```bash
cargo fmt --check
```

## Environment Variables

```bash
# Application
APP__ADDR=127.0.0.1:8580
APP__LOG_LEVEL=info

# PostgreSQL
PG__MAX_CONNECTIONS=100
PG__POOL_SIZE=25

# License (required for production)
LICENSE_KEY=your_license_key

# OpenSearch (optional)
OPENSEARCH_API_URL=https://opensearch.example.com
OPENSEARCH_API_TOKEN=your_token
OPENSEARCH_ENABLED=true
```

## Architecture

```
┌─────────────────┐
│   HTTP Client   │
└────────┬────────┘
         │
    ┌────▼────┐
    │  Axum   │
    │ Router  │
    └────┬────┘
         │
┌────────▼────────┐
│  Middleware     │
│  - Auth         │
│  - Rate Limit   │
│  - Metrics      │
└────────┬────────┘
         │
    ┌────▼────┐
    │ Handler │
    └────┬────┘
         │
┌────────▼────────┐
│  Connection     │
│     Pool        │
└────────┬────────┘
         │
    ┌────▼────┐
    │PostgreSQL│
    └─────────┘
```

## Performance

### Benchmark Results

Based on testing with standard hardware (8 CPU cores, 16GB RAM):

| Metric | Value | Conditions |
|--------|-------|------------|
| **Throughput** | 15,000+ req/s | Peak load with 1000 concurrent users |
| **Latency (p50)** | 0.8ms | Simple SELECT queries |
| **Latency (p99)** | 5ms | Simple SELECT queries |
| **Batch Processing** | 100 queries in <50ms | Optimized batch endpoint |
| **JSON Serialization** | 800K rows/s | 1KB payload per row |
| **Connection Pool** | 99% efficiency | 100 connection pool |

### Key Performance Features

- **Sub-millisecond latency** for simple queries
- **10,000+ requests/second** on modest hardware
- **Efficient connection pooling** reduces database load
- **Rate limiting** prevents abuse and ensures fair usage
- **Query batching** for optimized throughput

### Running Benchmarks

```bash
# Run performance benchmarks
cargo bench

# Run load tests
python scripts/load_test.py --standalone
```

See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for detailed performance analysis.

## Security

- API token authentication
- Per-query timeout enforcement
- SQL injection prevention through parameterized queries
- Audit logging for all database operations
- TLS/SSL support for encrypted connections

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting merge requests.

## License

This project is dual-licensed under MIT OR Apache-2.0. See [LICENSE](LICENSE) for details.

## Support

For issues and feature requests, please use the [GitLab issue tracker](https://gitlab.com/alexandre/pg-api/issues).

## Acknowledgments

- Built with [Axum](https://github.com/tokio-rs/axum) web framework
- Uses [deadpool-postgres](https://github.com/bikeshedder/deadpool) for connection pooling
- Observability powered by [OpenTelemetry](https://opentelemetry.io/)