# Development Guide

Guides for developers working on the ops-db-api codebase.

```{contents} Table of Contents
:depth: 2
:local: true
```

```{toctree}
:maxdepth: 2

testing
debugging-buffering
redis-inspection
contributing
```

## Overview

This section covers:

- **Testing**: Running and writing tests
- **Debugging**: Troubleshooting buffering and replication
- **Redis Inspection**: Examining cache and buffer state
- **Contributing**: Code style and PR process

## Development Environment

See {doc}`../quickstart/installation` for setting up your development environment.

## Quick Start

```bash
# Clone repository
git clone https://github.com/ccatobs/ops-db-api.git
cd ops-db-api

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Run tests
pytest

# Start development server
uvicorn ccat_ops_db_api.main:app --reload
```

## Development Tokens

The system automatically creates development API tokens when initializing the database in development mode. These tokens are reusable across database resets and are only valid in development environments.

### Automatic Creation

Development tokens are automatically seeded when:

1. Running `opsdb_init` with `data_archive_mode="development"`
2. Starting the API with `ENVIRONMENT=development` (fallback if not seeded during init)

### Token Format

Development tokens are prefixed with `ops_api_token_dev_` to clearly identify them:

```text
ops_api_token_dev_<hash>
```

### Default Tokens

Two tokens are created by default:

- **service_dev-pipeline**: For data pipeline automation
  \- Scopes: `read:observations`, `write:observations`, `read:data`, `write:data`
- **service_dev-cli**: For CLI tools and scripts
  \- Scopes: `read:*`, `write:*`

### Using Development Tokens

After database initialization, tokens are printed to the console. Save them in your development environment:

```bash
export DEV_PIPELINE_TOKEN="ops_api_token_dev_..."
export DEV_CLI_TOKEN="ops_api_token_dev_..."
```

Use in Python scripts:

```python
import os
import requests

token = os.getenv("DEV_PIPELINE_TOKEN")
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(
    "http://localhost:8000/api/observations",
    headers=headers
)
```

Use in cURL:

```bash
curl -H "Authorization: Bearer $DEV_PIPELINE_TOKEN" \
     http://localhost:8000/api/observations
```

### Customization

Set the `DEV_TOKEN_SECRET` environment variable to customize token generation:

```bash
export DEV_TOKEN_SECRET="your-custom-secret"
```

This ensures tokens are deterministic but unique to your development setup.

### Troubleshooting

**Tokens not created?**
\- Verify `data_archive_mode="development"` when running `opsdb_init`
\- Check that `ENVIRONMENT=development` is set for API startup fallback
\- Check logs for seeding errors

**Token rejected?**
\- Verify environment is set to development/dev/local
\- Check that token starts with `ops_api_token_dev_`
\- Review logs for security warnings

**Token not found after database reset?**
\- Tokens are recreated automatically on next initialization
\- Same `DEV_TOKEN_SECRET` = same tokens (deterministic)
\- Check console output during initialization for token values

## Next Steps

- {doc}`testing` - Writing and running tests
- {doc}`debugging-buffering` - Debugging transaction buffering
- {doc}`redis-inspection` - Redis debugging commands
- {doc}`contributing` - Contributing guidelines