👯 Split API into Guardian and Mediator modes (#74)

Guardian mode endpoints:
- /guardian/*
- /key
  - /auxiliary/generate
  - /election/generate
- /tally
  - /decrypt-share
- /ping

Mediator mode endtpoints:
- /ballot/*
- /election/*
- /key/election/combine
- /tally
  - /
  - /append
  - /decrypt
- /ping

The mode is determined on startup by the `API_MODE` environment variable, which can be set to either `guardian` or `mediator` (default).

The docker image accepts this environment variable if provided, and a docker-compose file has been added for easy local execution of the image in both guardian and mediator modes.

Author: rkorsak

.vscode/launch.json

@@ -2,13 +2,33 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Web API",
+            "name": "Guardian Web API",
             "type": "python",
             "request": "launch",
             "program": "${workspaceRoot}/app/main.py",
             "console": "integratedTerminal",
+            "args": [
+                "--port",
+                "8001"
+            ],
             "env": {
-                "PYTHONPATH": "${workspaceRoot}"
+                "PYTHONPATH": "${workspaceRoot}",
+                "API_MODE": "guardian"
+            }
+        },
+        {
+            "name": "Mediator Web API",
+            "type": "python",
+            "request": "launch",
+            "program": "${workspaceRoot}/app/main.py",
+            "console": "integratedTerminal",
+            "args": [
+                "--port",
+                "8000"
+            ],
+            "env": {
+                "PYTHONPATH": "${workspaceRoot}",
+                "API_MODE": "mediator"
             }
         }
     ]

Dockerfile

@@ -1,17 +1,21 @@
-FROM python:3.8
+FROM python:3.8 AS base
 ENV host 0.0.0.0
-
+ENV port 8000
 RUN apt update && apt-get install -y \
     libgmp-dev \
     libmpfr-dev \
     libmpc-dev
 RUN pip install pipenv
-
 COPY ./Pipfile* /tmp/
 RUN cd /tmp && pipenv lock --requirements > requirements.txt
 RUN pip install -r /tmp/requirements.txt
 
-COPY ./app /app
+FROM base AS dev
+VOLUME [ "/app" ]
+EXPOSE $port
+CMD uvicorn app.main:app --reload --host "$host" --port "$port"
 
-EXPOSE 8000
-CMD uvicorn app.main:app --host "$host" --port 8000
+FROM base AS prod
+COPY ./app /app
+EXPOSE $port
+CMD uvicorn app.main:app --host "$host" --port "$port"

Makefile

@@ -6,6 +6,8 @@ CONTAINER_NAME = electionguard_web_api
 CONTAINER_ADDRESS ?= 0.0.0.0
 CONTAINER_PORT ?= 8000
 IMAGE_NAME = electionguard_web_api
+# Supports either "guardian" or "mediator" modes
+API_MODE = mediator
 
 all: environment lint start
 
@@ -51,10 +53,13 @@ start:
 
 # Docker
 docker-build:
-	docker build -t $(IMAGE_NAME) .
+	DOCKER_BUILDKIT=1 docker build -t $(IMAGE_NAME) .
 
 docker-run:
-	docker run -d --name $(CONTAINER_NAME) -p $(CONTAINER_PORT):8000 -e host=$(CONTAINER_ADDRESS) $(IMAGE_NAME)
+	COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose up --build
+
+docker-dev:
+	COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose -f docker-compose.dev.yml up --build
 
 # Linting
 lint:

README.md

@@ -1,56 +1,75 @@
 ![Microsoft Defending Democracy Program: ElectionGuard](images/electionguard-banner.svg)
 
-#  🗳️ ElectionGuard Web API
+# 🗳️ ElectionGuard Web API
 
 ![docker version](https://img.shields.io/docker/v/electionguard/electionguard-web-api) ![docker pulls](https://img.shields.io/docker/pulls/electionguard/electionguard-web-api) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/context:python) [![Total alerts](https://img.shields.io/lgtm/alerts/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/alerts/) [![Documentation Status](https://readthedocs.org/projects/electionguard-web-api/badge/?version=latest)](https://electionguard-web-api.readthedocs.io) [![license](https://img.shields.io/github/license/microsoft/electionguard-web-api)](LICENSE)
 
+This is a python API that utilizes [`electionguard-python`](https://github.com/microsoft/electionguard-python) to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs).
 
-This is a python API that utilizes [`electionguard-python`](https://github.com/microsoft/electionguard-python) to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs
-).
+## 👯‍♀️ Two APIs in One
 
+The application can run in one of two modes:
 
-## 💻 Requirements
+- `guardian` mode runs features used by Guardians (key ceremony actions, partial tally decryption, etc.)
+- `mediator` mode runs features used by Mediators (ballot encryption, casting, spoiling, etc.)
+
+In practice, you will likely need to run at least one instance of each mode. We provide a single codebase and Docker image, but the mode can be set at runtime.
+
+## 🐳 Running with Docker
+
+If you run Docker and want to get started quickly, we provide a Dockerfile and docker-compose.yml.
+
+Run both APIs at the same time:
+
+```bash
+make docker-run
+```
+
+Or run both APIs in development mode, with automatic reloading on file change:
+
+```bash
+make docker-dev
+```
+
+After either command, you will find the `mediator` API running at http://127.0.0.1:8000 and the `guardian` API at http://127.0.0.1:8001
+
+## 🐍 Running with Python
+
+### Requirements
 
 _These requirements line up with [electionguard-python](https://github.com/microsoft/electionguard-python/blob/main/README.md#-requirements)._
 
 - [Python 3.8](https://www.python.org/downloads/) is <ins>**required**</ins> to develop this API. If developer uses multiple versions of python, [pyenv](https://github.com/pyenv/pyenv) is suggested to assist version management.
 - [GNU Make](https://www.gnu.org/software/make/manual/make.html) is used to simplify the commands and GitHub Actions. This approach is recommended to simplify the command line experience. This is built in for MacOS and Linux. For Windows, setup is simpler with [Chocolatey](https://chocolatey.org/install) and installing the provided [make package](https://chocolatey.org/packages/make). The other Windows option is [manually installing make](http://gnuwin32.sourceforge.net/packages/make.htm).
-- [Gmpy2](https://gmpy2.readthedocs.io/en/latest/) is used for [Arbitrary-precision arithmetic](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic) which
-has its own [installation requirements (native C libraries)](https://gmpy2.readthedocs.io/en/latest/intro.html#installation) on Linux and MacOS.  **⚠️ Note:** _This is not required for Windows but the python package must be installed with the precompiled libraries._
 - [pipenv](https://github.com/pypa/pipenv) is used to configure the python environment. Installation instructions can be found [here](https://github.com/pypa/pipenv#installation).
 
-## 🚀 Quick Start
+### Quick Start
 
 Using [**make**](https://www.gnu.org/software/make/manual/make.html), installation and startup can be run with one command: 
 
-```
-make
-```
+To set up the environment:
 
-To start the api:
-```
-make start
+```bash
+make environment
 ```
 
-## 🛠 Debugging
+To start the api:
 
-For local debugging with Visual Studio Code, choose the `Web API` option from the dropdown in the Run menu.  Once the server is up, you can easily hit your breakpoints.
+```bash
+make start API_MODE=mediator
+```
 
-If the code fails to run, [make sure your Python interpreter is set](https://code.visualstudio.com/docs/python/environments) to use your pipenv environment.
+OR
 
-## 🐳 Docker
-A DockerFile is available to quickly create and run a docker container.
+```bash
+make start API_MODE=guardian
+```
 
+### Debugging
 
-Build docker container:
-```
-make docker-build
-```
+For local debugging with Visual Studio Code, choose the `Guardian Web API` or `Mediator Web API` options from the dropdown in the Run menu. Once the server is up, you can easily hit your breakpoints.
 
-Run docker container:
-```
-make docker-run
-```
+If the code fails to run, [make sure your Python interpreter is set](https://code.visualstudio.com/docs/python/environments) to use your pipenv environment.
 
 ## 🧪 Testing
 
@@ -60,33 +79,35 @@ A Postman collection is available to test the API located in the `/tests` folder
 
 **FastApi** defaultly has API documentation built in. The following is available after running:
 
-- **[SwaggerUI](https://github.com/swagger-api/swagger-ui)** at [`http://127.0.0.1:8000/docs`](http://127.0.0.1:8000/docs)
+- **[SwaggerUI](https://github.com/swagger-api/swagger-ui)** at [`http://127.0.0.1:8000/docs`](http://127.0.0.1:8000/docs) or [`http://127.0.0.1:8001/docs`](http://127.0.0.1:8001/docs), depending on the API mode
 
-- **[ReDoc](https://github.com/Redocly/redoc)** at [`http://127.0.0.1:8000/redoc`](http://127.0.0.1:8000/redoc)
+- **[ReDoc](https://github.com/Redocly/redoc)** at [`http://127.0.0.1:8000/redoc`](http://127.0.0.1:8000/redoc) or [`http://127.0.0.1:8001/redoc`](http://127.0.0.1:8001/redoc)
 
 Overviews of the API itself are available on:
 
 - [GitHub Pages](https://microsoft.github.io/electionguard-web-api/)
 - [Read the Docs](https://electionguard-web-api.readthedocs.io/)
 
 ## 🗄 Archived
+
 As of 06/15/2020, the previous C wrapped implementation was transitioned to the python version. ElectionGuard development has transitioned to the [ElectionGuard-Python](https://github.com/microsoft/electionguard-python) Repo. The old version is available using the `dotnet-api` tag.
 
 ## 🤝 Contributing
 
-This project encourages community contributions for development, testing, documentation, code review, and performance analysis, etc.  For more information on how to contribute, see [the contribution guidelines][Contributing]
+This project encourages community contributions for development, testing, documentation, code review, and performance analysis, etc. For more information on how to contribute, see [the contribution guidelines][contributing]
 
 ### Code of Conduct
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
 ### Reporting Issues
 
-Please report any bugs, feature requests, or enhancements using the [GitHub Issue Tracker](https://github.com/microsoft/electionguard-web-api/issues).  Please do not report any security vulnerabilities using the Issue Tracker.  Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).  See the [Security Documentation][Security] for more information.
+Please report any bugs, feature requests, or enhancements using the [GitHub Issue Tracker](https://github.com/microsoft/electionguard-web-api/issues). Please do not report any security vulnerabilities using the Issue Tracker. Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). See the [Security Documentation][security] for more information.
 
 ### Have Questions?
 
 Electionguard would love for you to ask questions out in the open using GitHub Issues. If you really want to email the ElectionGuard team, reach out at [email protected].
 
 ## License
-This repository is licensed under the [MIT License]
+
+This repository is licensed under the [MIT License]

app/api/v1/api.py

@@ -1,11 +1,19 @@
 from fastapi import APIRouter
-
-from app.api.v1.endpoints import ballot, election, guardian, key, ping, tally
+from app.core.config import settings, ApiMode
+from . import common
 
 api_router = APIRouter()
-api_router.include_router(ballot.router, prefix="/ballot", tags=["ballot"])
-api_router.include_router(election.router, prefix="/election", tags=["election"])
-api_router.include_router(guardian.router, prefix="/guardian", tags=["guardian"])
-api_router.include_router(key.router, prefix="/key", tags=["key"])
-api_router.include_router(ping.router, prefix="/ping", tags=["ping"])
-api_router.include_router(tally.router, prefix="/tally", tags=["tally"])
+
+if settings.API_MODE == ApiMode.guardian:
+    from . import guardian
+
+    api_router.include_router(guardian.router)
+elif settings.API_MODE == ApiMode.mediator:
+    from . import mediator
+
+    api_router.include_router(mediator.router)
+else:
+    raise ValueError(f"Unknown API mode: {settings.API_MODE}")
+
+
+api_router.include_router(common.router)

app/api/v1/common/__init__.py

@@ -0,0 +1 @@
+from .routes import router

app/api/v1/endpoints/ping.py app/api/v1/common/ping.pyapp/api/v1/endpoints/ping.py renamed to app/api/v1/common/ping.py

@@ -2,10 +2,12 @@
 
 from fastapi import APIRouter
 
+from ..tags import UTILITY
+
 router = APIRouter()
 
 
-@router.get("", response_model=str)
+@router.get("", response_model=str, tags=[UTILITY])
 def ping() -> Any:
     """
     Ensure API can be pinged

app/api/v1/common/routes.py

@@ -0,0 +1,6 @@
+from fastapi import APIRouter
+from . import ping
+
+router = APIRouter()
+
+router.include_router(ping.router, prefix="/ping")

app/api/v1/endpoints/__init__.py

@@ -0,0 +1 @@
+from .routes import router