✨ Implement Tracking Word Conversions (#105)

- Convert Hash to Words
- Convert Words to Hash
- Create Postman tests for examples

Author: keithrfung

app/api/v1/mediator/routes.py

@@ -3,10 +3,12 @@
 from . import election
 from . import key
 from . import tally
+from . import tracker
 
 router = APIRouter()
 
 router.include_router(election.router, prefix="/election")
 router.include_router(key.router, prefix="/key")
 router.include_router(ballot.router, prefix="/ballot")
 router.include_router(tally.router, prefix="/tally")
+router.include_router(tracker.router, prefix="/tracker")

app/api/v1/mediator/tracker.py

@@ -0,0 +1,36 @@
+from typing import Any
+from electionguard.group import ElementModQ
+from electionguard.serializable import read_json_object
+from electionguard.tracker import tracker_hash_to_words, tracker_words_to_hash
+from fastapi import APIRouter, Body
+
+from ..models import (
+    TrackerHash,
+    TrackerHashRequest,
+    TrackerWords,
+    TrackerWordsRequest,
+)
+from ..tags import UTILITY
+
+router = APIRouter()
+
+
+@router.post("/hash", tags=[UTILITY])
+def convert_tracker_to_hash(request: TrackerHashRequest = Body(...)) -> Any:
+    """
+    Convert tracker from human readable / friendly words to hash
+    """
+
+    tracker_hash = tracker_words_to_hash(request.tracker_words, request.seperator)
+    return TrackerHash(tracker_hash=str(tracker_hash))
+
+
+@router.post("/words", tags=[UTILITY])
+def convert_tracker_to_words(request: TrackerWordsRequest = Body(...)) -> Any:
+    """
+    Convert tracker from hash to human readable / friendly words
+    """
+
+    tracker_hash = read_json_object(request.tracker_hash, ElementModQ)
+    tracker_words = tracker_hash_to_words(tracker_hash, request.seperator)
+    return TrackerWords(tracker_words=tracker_words)

app/api/v1/models/__init__.py

@@ -4,3 +4,4 @@
 from .guardian import *
 from .key import *
 from .tally import *
+from .tracker import *

app/api/v1/models/tracker.py

@@ -0,0 +1,27 @@
+from electionguard.tracker import DEFAULT_SEPERATOR
+from .base import Base
+
+__all__ = [
+    "TrackerWordsRequest",
+    "TrackerWords",
+    "TrackerHashRequest",
+    "TrackerHash",
+]
+
+
+class TrackerWordsRequest(Base):
+    tracker_hash: str
+    seperator: str = DEFAULT_SEPERATOR
+
+
+class TrackerWords(Base):
+    tracker_words: str
+
+
+class TrackerHashRequest(Base):
+    tracker_words: str
+    seperator: str = DEFAULT_SEPERATOR
+
+
+class TrackerHash(Base):
+    tracker_hash: str

tests/postman/ElectionGuard Web Api.postman_collection.json

@@ -1,6 +1,6 @@
 {
 	"info": {
-		"_postman_id": "b6c83d85-3899-4ebb-ba68-679bec81bd52",
+		"_postman_id": "81086475-1eea-4021-b602-b7441a7e86e6",
 		"name": "ElectionGuard Web Api",
 		"description": "A collection of API calls for ElectionGuard Web Api",
 		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
@@ -111,7 +111,7 @@
 								{
 									"listen": "test",
 									"script": {
-										"id": "44698cce-1da1-4296-b616-18dc0eae8a53",
+										"id": "861b0dd4-0835-4f65-8f07-155ec5fb487e",
 										"exec": [
 											"pm.test(\"Ballots are returned in the same order as the request\", function () {",
 											"    const requestJson = JSON.parse(pm.request.body.toString())",
@@ -183,7 +183,7 @@
 								{
 									"listen": "test",
 									"script": {
-										"id": "7bc63d84-ffdb-4401-a1ba-dd94aa8066fa",
+										"id": "9072fd9f-9ed4-47e3-86eb-9e31275131a0",
 										"exec": [
 											"pm.test(\"Ballots are returned in the same order as the request\", function () {",
 											"    const requestJson = JSON.parse(pm.request.body.toString())",
@@ -244,7 +244,7 @@
 						{
 							"listen": "prerequest",
 							"script": {
-								"id": "e6bc2390-9e1b-4acf-a7b4-76f961241303",
+								"id": "df799c09-3a81-417c-bf1c-a2eac2ffab2a",
 								"type": "text/javascript",
 								"exec": [
 									""
@@ -254,7 +254,7 @@
 						{
 							"listen": "test",
 							"script": {
-								"id": "e8558e10-d6d4-4a3f-804e-c3ff2ce9f4d1",
+								"id": "d4204e33-758b-4476-b71e-e75c789f8e00",
 								"type": "text/javascript",
 								"exec": [
 									""
@@ -477,13 +477,73 @@
 								}
 							},
 							"response": []
+						},
+						{
+							"name": "Tracker hash to words",
+							"request": {
+								"method": "POST",
+								"header": [],
+								"body": {
+									"mode": "raw",
+									"raw": "{\n    \"tracker_hash\":\"82295779859697986364440242162484040502484343758343249767620990301560940975228\"\n}",
+									"options": {
+										"raw": {
+											"language": "json"
+										}
+									}
+								},
+								"url": {
+									"raw": "{{mediator-url}}/api/{{version}}/tracker/words",
+									"host": [
+										"{{mediator-url}}"
+									],
+									"path": [
+										"api",
+										"{{version}}",
+										"tracker",
+										"words"
+									]
+								},
+								"description": "Get a readable / friendly word tracker from the hash"
+							},
+							"response": []
+						},
+						{
+							"name": "Tracker words to hash",
+							"request": {
+								"method": "POST",
+								"header": [],
+								"body": {
+									"mode": "raw",
+									"raw": "{\n        \"tracker_words\": \"abacus-abacus-amazement-arithmetic-assist-adjustment-assembly-alligator-antique-age-arena-airport-acquaintance-accomplishment-accord-apparel-airline-abacus-artist-adjective-assumption-aim-analogue-album-accelerant-advice-allergist-antibody-article-agent-appreciation-approach-assembly-appeal\"\n}",
+									"options": {
+										"raw": {
+											"language": "json"
+										}
+									}
+								},
+								"url": {
+									"raw": "{{mediator-url}}/api/{{version}}/tracker/hash",
+									"host": [
+										"{{mediator-url}}"
+									],
+									"path": [
+										"api",
+										"{{version}}",
+										"tracker",
+										"hash"
+									]
+								},
+								"description": "Get a readable / friendly word tracker from the hash"
+							},
+							"response": []
 						}
 					],
 					"event": [
 						{
 							"listen": "prerequest",
 							"script": {
-								"id": "93000645-0e5d-4d68-9b76-bc2fc8fb6e8a",
+								"id": "2a3c6fcf-7c49-4a51-aa97-26aaa2544240",
 								"type": "text/javascript",
 								"exec": [
 									""
@@ -493,7 +553,7 @@
 						{
 							"listen": "test",
 							"script": {
-								"id": "c68bbfaf-adac-418f-87f7-f2b6f81e6fd1",
+								"id": "d7ef01db-6909-464c-b70e-8748b93d9631",
 								"type": "text/javascript",
 								"exec": [
 									""
@@ -754,7 +814,7 @@
 								{
 									"listen": "test",
 									"script": {
-										"id": "74f0deec-8658-42ed-af3e-77287ee6c656",
+										"id": "0a8fc220-b377-479b-9b3a-70fe85ee1660",
 										"exec": [
 											"pm.test(\"Ballot shares are returned in the same order as the request\", function () {",
 											"    const requestJson = JSON.parse(pm.request.body.toString())",
@@ -841,7 +901,7 @@
 						{
 							"listen": "prerequest",
 							"script": {
-								"id": "7690e768-e219-435e-988b-705406e4713b",
+								"id": "9539fa67-e461-4138-b3b9-691dc8e5284a",
 								"type": "text/javascript",
 								"exec": [
 									""
@@ -851,7 +911,7 @@
 						{
 							"listen": "test",
 							"script": {
-								"id": "072f942b-08c3-42d8-877b-16428077c390",
+								"id": "724d61c2-5cf6-43ee-8994-0c9d596c1fea",
 								"type": "text/javascript",
 								"exec": [
 									""
@@ -870,7 +930,7 @@
 		{
 			"listen": "prerequest",
 			"script": {
-				"id": "8b52952d-726b-48cb-b3eb-7f19bfa44c61",
+				"id": "3109002d-bdb4-4cf2-8ad8-d507c48afd57",
 				"type": "text/javascript",
 				"exec": [
 					""
@@ -880,7 +940,7 @@
 		{
 			"listen": "test",
 			"script": {
-				"id": "a0dc5753-cb73-44ad-9b75-4efe6c78ed79",
+				"id": "8d5bbb95-fad8-4ee4-b727-4cbb6b39fc3f",
 				"type": "text/javascript",
 				"exec": [
 					"pm.test(\"Status code is 200\", () => {",