Development Guide
=================

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

.. contents:: Table of Contents
   :local:
   :depth: 2

.. 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
-----------

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: bash

   export DEV_PIPELINE_TOKEN="ops_api_token_dev_..."
   export DEV_CLI_TOKEN="ops_api_token_dev_..."

Use in Python scripts:

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: 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