# OWS Users

## Overview

This microservice manages our users across our different applications (Mobile
Analytics, OA and Workstation). At the moment, it provides some basic OAUTH2
endpoints. In the future: this microservice will be responsible for handling
user related data and information.

## Getting Started

### Requirements

* python3.11

### Installation

The installation is very straightforward, but make sure you are using the closest version
from whats specified at the `.python-version` file.

#### MacOS
The most reliable method to avoid issues with MacOS built-in python3 version
is to use `pyenv` (https://github.com/pyenv/pyenv), installed via `brew` (https://formulae.brew.sh/formula/pyenv).

Once you have pyenv installed, you just need to
`pyenv install 3.x.y` and then `pyenv global 3.x.y` before start working in the repo.
Once you are in the (env), make sure these two commands output the same expected version
```
python --version
env/bin/python --version
```
If they do, you are ready to go!

<br/>

#### Windows
Just ask for a remote VM that has it installed for you.

You'll also need a `~/.split` file which can be empty but which must exist.
```bash
  touch ~/.split
```

## Get the code
  ```bash
  # clone the repo
  git clone git@github.com:theorchard/ows-users.git
  cd ows-users/

  # add your fork as a remote
  git remote add <YOUR USERNAME> git@github.com:<YOUR USERNAME>/ows-users.git
  ```

## Running

* #### Set up a virtual Python environment

  When you have the local copy, you need to create a running environment. Run:

  ```bash
  # create python3.11 virtual environment
  python3.11 -m venv env
  # activate the environment
  source env/bin/activate
  ```

* #### Install dependencies

  make command: `make pip_dev`

  make command: `make dev`

  You may need to run `pip install wheel` as well if you see errors involving `bdist_wheel`.

* #### Running linter

  We use [ruff](https://docs.astral.sh/ruff/) as the linter; rules can be seen in `ruff.toml`.

  ```bash
  ruff check users/ tests/
  ```

  make command: `make lint`

  ##### Installing pre-commit hook (optional)

  If you want the linter to run before you commit (it won't block your commit, it'll just let you know what's up), run
  ```
  cp .pre-commit-config.yaml.shadow .pre-commit-config.yaml
  pre-commit install
  ```

  If you DO want it to block your commit, remove the `args: [--exit-zero]` line from the file.

* #### Running tests

  We use [Pytest](http://pytest.org/) to run our tests.  Make sure you have AWS account credentials set by executing the `awsume prod` command.

    ```bash
    uv run pytest tests/unit
    uv run pytest tests/integration
    ```

  [Pydebug](https://docs.python.org/3/library/pdb.html) is useful for debugging

    ```bash
    import pdb; pdb.set_trace()
    ```
  Place that anywhere in the code and it will pause there during the test and you can inspect variables.

* #### :warning: Using moto
  If you are using a moto decorator you **must** explicitly reload the module being called **if** that module declares the boto client globally. See details about the issue [here](https://github.com/spulec/moto/issues/1793).
  ```py
  from importlib import reload
  from moto import mock_sns
  from users.logic import devices

  @mock_sns
  def test_something():
      reload(devices)
    ...
  ```

* #### Configure the server

  Server configurations can be found in `/users/config.py`. You can set environment variables in terminal.

  ```bash
  export AR_MYSQL_HOST=squad.db.theorchard.io
  ```
  For AWS secrets based configurations, you may need to hard code your values (remember not to commit them).

* #### Launch the server

  Make sure you are in the virtual environment. You should see `(env) $`
  prefixed in your prompt.

  ```bash
  uv run python dev.py
  ```

  make command: `make dev`

* #### Adding Handlers to Swagger Registry

  Our API documentation is held in https://swagger.theorchard.io/. When creating a new handler or updating functionality, please try to remember to update the `ows-users.yaml` file in `/specs` to keep our docs up to date.

  Use an editor like https://editor.swagger.io/ to check the syntax for issues before pushing.

  After the update, run the [docs-swagger-ui-pipeline](https://pipeline.theorchard.io/job/docs-swagger-ui-pipeline/) to see the changes in the actual registry.

## Developing (Docker)
1. Make sure you've set up your `.env` file:

```
cp .env.shadow .env
```

FILL out `.env` accordingly

2. Load your environment:

```bash
awsume prod
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 086679231553.dkr.ecr.us-east-1.amazonaws.com
source .env
```

3. Run the hot-reload version of the ows-users Docker image - it watches for changes on your volume/laptop:

```bash
make up
```

You can make requests against it at http://localhost:8888.

4. If you feel the need to run the deploy-version of the ows-users Docker image (it's uwsgi):

```bash
make up_deploy
```

You can make requests against it at http://localhost:8889.

5. You can run unit tests and lint in docker:

```bash
make docker_unit_lint
```

6. When you're done, bring down your Docker containers:

```bash
make down
```