Merge pull request #128 from docat-org/fastapi

Refactor to use FastAPI instead of Flask

Author: fliiiix

.github/workflows/docat.yml

@@ -29,6 +29,11 @@ jobs:
         run: |
           python -m poetry run flake8 docat tests
 
+      - name: run backend static code analysis
+        working-directory: docat
+        run: |
+          python -m poetry run mypy .
+
       - name: run backend tests
         working-directory: docat
         run: |

Dockerfile

@@ -52,4 +52,4 @@ RUN cp docat/nginx/default /etc/nginx/http.d/default.conf
 COPY --from=backend /app /app/docat
 
 ENTRYPOINT ["/usr/bin/dumb-init", "--"]
-CMD ["sh", "-c", "nginx && .venv/bin/python -m gunicorn --access-logfile - --bind=0.0.0.0:5000 docat.app:app"]
+CMD ["sh", "-c", "nginx && .venv/bin/python -m uvicorn --host 0.0.0.0 --port 5000 docat.app:app"]

doc/getting-started.md

@@ -21,6 +21,10 @@ Use `docatl --help` to discover all other commands to manage your docat document
 
 The following sections document the RAW API endpoints you can `curl`.
 
+The API specification is exposed as OpenAPI at http://localhost:8000/api/v1/openapi.json
+and available with Swagger UI at http://localhost:8000/api/docs and a pure documentation
+is available with redoc at http://localhost:8000/api/redoc.
+
 #### Upload your documentation
 
 You can upload any static HTML site by zipping it and

docat/docat/__main__.py

@@ -1,5 +1,7 @@
 import os
 
+import uvicorn
+
 from docat.app import app
 
 if __name__ == "__main__":
@@ -8,4 +10,4 @@
     except ValueError:
         port = 5000
 
-    app.run("0.0.0.0", port=port)
+    uvicorn.run(app, host="0.0.0.0", port=port)

docat/docat/app.py

@@ -9,126 +9,148 @@
 """
 import os
 import secrets
-from http import HTTPStatus
+import shutil
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Optional
 
-from flask import Flask, request, send_from_directory
+from fastapi import Depends, FastAPI, File, Header, Response, UploadFile, status
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
 from tinydb import Query, TinyDB
-from werkzeug.utils import secure_filename
 
 from docat.utils import UPLOAD_FOLDER, calculate_token, create_nginx_config, create_symlink, extract_archive, remove_docs
 
-app = Flask(__name__)
-app.config["UPLOAD_FOLDER"] = Path(os.getenv("DOCAT_DOC_PATH", UPLOAD_FOLDER))
-app.config["MAX_CONTENT_LENGTH"] = 100 * 1024 * 1024  # 100M
-app.db = TinyDB("db.json")
+#: Holds the FastAPI application
+app = FastAPI(
+    title="docat",
+    description="API for docat, https://github.com/docat-org/docat",
+    openapi_url="/api/v1/openapi.json",
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+)
+#: Holds an instance to the TinyDB
+db = TinyDB("db.json")
+#: Holds the static base path where the uploaded documentation artifacts are stored
+DOCAT_UPLOAD_FOLDER = Path(os.getenv("DOCAT_DOC_PATH", UPLOAD_FOLDER))
 
 
-@app.route("/api/<project>/<version>", methods=["POST"])
-def upload(project, version):
-    if "file" not in request.files:
-        return {"message": "No file part in the request"}, HTTPStatus.BAD_REQUEST
+def get_db():
+    """Return the cached TinyDB instance."""
+    return db
 
-    uploaded_file = request.files["file"]
-    if uploaded_file.filename == "":
-        return {"message": "No file selected for uploading"}, HTTPStatus.BAD_REQUEST
 
-    project_base_path = app.config["UPLOAD_FOLDER"] / project
+@dataclass
+class TokenStatus:
+    valid: bool
+    reason: Optional[str] = None
+
+
+class ApiResponse(BaseModel):
+    message: str
+
+
+class ClaimResponse(ApiResponse):
+    token: str
+
+
+@app.post("/api/{project}/{version}", response_model=ApiResponse, status_code=status.HTTP_201_CREATED)
+def upload(
+    project: str,
+    version: str,
+    response: Response,
+    file: UploadFile = File(...),
+    docat_api_key: Optional[str] = Header(None),
+    db: TinyDB = Depends(get_db),
+):
+    project_base_path = DOCAT_UPLOAD_FOLDER / project
     base_path = project_base_path / version
-    target_file = base_path / secure_filename(uploaded_file.filename)
+    target_file = base_path / file.filename
 
     if base_path.exists():
-        token = request.headers.get("Docat-Api-Key")
-        result = check_token_for_project(token, project)
-        if result is True:
+        token_status = check_token_for_project(db, docat_api_key, project)
+        if token_status.valid:
             remove_docs(project, version)
         else:
-            return result
+            response.status_code = status.HTTP_401_UNAUTHORIZED
+            return ApiResponse(message=token_status.reason)
 
     # ensure directory for the uploaded doc exists
     base_path.mkdir(parents=True, exist_ok=True)
 
     # save the uploaded documentation
-    uploaded_file.save(str(target_file))
-    extract_archive(target_file, base_path)
+    file.file.seek(0)
+    with target_file.open("wb") as buffer:
+        shutil.copyfileobj(file.file, buffer)
 
+    extract_archive(target_file, base_path)
     create_nginx_config(project, project_base_path)
-
-    return {"message": "File successfully uploaded"}, HTTPStatus.CREATED
+    return ApiResponse(message="File successfully uploaded")
 
 
-@app.route("/api/<project>/<version>/tags/<new_tag>", methods=["PUT"])
-def tag(project, version, new_tag):
-    source = version
-    destination = app.config["UPLOAD_FOLDER"] / project / new_tag
+@app.put("/api/{project}/{version}/tags/{new_tag}", response_model=ApiResponse, status_code=status.HTTP_201_CREATED)
+def tag(project: str, version: str, new_tag: str, response: Response):
+    destination = DOCAT_UPLOAD_FOLDER / project / new_tag
 
-    if create_symlink(source, destination):
-        return (
-            {"message": f"Tag {new_tag} -> {version} successfully created"},
-            HTTPStatus.CREATED,
-        )
+    if create_symlink(version, destination):
+        return ApiResponse(message=f"Tag {new_tag} -> {version} successfully created")
     else:
-        return (
-            {"message": f"Tag {new_tag} would overwrite an existing version!"},
-            HTTPStatus.CONFLICT,
-        )
+        response.status_code = status.HTTP_409_CONFLICT
+        return ApiResponse(message=f"Tag {new_tag} would overwrite an existing version!")
 
 
-@app.route("/api/<project>/claim", methods=["GET"])
-def claim(project):
+@app.get(
+    "/api/{project}/claim",
+    response_model=ClaimResponse,
+    status_code=status.HTTP_201_CREATED,
+    responses={status.HTTP_409_CONFLICT: {"model": ApiResponse}},
+)
+def claim(project: str, db: TinyDB = Depends(get_db)):
     Project = Query()
-    table = app.db.table("claims")
+    table = db.table("claims")
     result = table.search(Project.name == project)
     if result:
-        return (
-            {"message": f"Project {project} is already claimed!"},
-            HTTPStatus.CONFLICT,
-        )
+        return JSONResponse(status_code=status.HTTP_409_CONFLICT, content={"message": f"Project {project} is already claimed!"})
 
     token = secrets.token_hex(16)
     salt = os.urandom(32)
     token_hash = calculate_token(token, salt)
     table.insert({"name": project, "token": token_hash, "salt": salt.hex()})
 
-    return {"message": f"Project {project} successfully claimed", "token": token}, HTTPStatus.CREATED
+    return ClaimResponse(message=f"Project {project} successfully claimed", token=token)
 
 
-@app.route("/api/<project>/<version>", methods=["DELETE"])
-def delete(project, version):
-    token = request.headers.get("Docat-Api-Key")
-
-    result = check_token_for_project(token, project)
-    if result is True:
+@app.delete("/api/{project}/{version}", response_model=ApiResponse, status_code=status.HTTP_200_OK)
+def delete(project: str, version: str, response: Response, docat_api_key: str = Header(None), db: TinyDB = Depends(get_db)):
+    token_status = check_token_for_project(db, docat_api_key, project)
+    if token_status.valid:
         message = remove_docs(project, version)
         if message:
-            return ({"message": message}, HTTPStatus.NOT_FOUND)
+            response.status_code = status.HTTP_404_NOT_FOUND
+            return ApiResponse(message=message)
         else:
-            return (
-                {"message": f"Successfully deleted version '{version}'"},
-                HTTPStatus.OK,
-            )
+            return ApiResponse(message=f"Successfully deleted version '{version}'")
     else:
-        return result
+        response.status_code = status.HTTP_401_UNAUTHORIZED
+        return ApiResponse(message=token_status.reason)
 
 
-def check_token_for_project(token, project):
+def check_token_for_project(db, token, project) -> TokenStatus:
     Project = Query()
-    table = app.db.table("claims")
+    table = db.table("claims")
     result = table.search(Project.name == project)
 
     if result and token:
         token_hash = calculate_token(token, bytes.fromhex(result[0]["salt"]))
         if result[0]["token"] == token_hash:
-            return True
+            return TokenStatus(True)
         else:
-            return ({"message": f"Docat-Api-Key token is not valid for {project}"}, HTTPStatus.UNAUTHORIZED)
+            return TokenStatus(False, f"Docat-Api-Key token is not valid for {project}")
     else:
-        return ({"message": f"Please provide a header with a valid Docat-Api-Key token for {project}"}, HTTPStatus.UNAUTHORIZED)
+        return TokenStatus(False, f"Please provide a header with a valid Docat-Api-Key token for {project}")
 
 
 # serve_local_docs for local testing without a nginx
 if os.environ.get("DOCAT_SERVE_FILES"):
-
-    @app.route("/doc/<path:path>")
-    def serve_local_docs(path):
-        return send_from_directory(app.config["UPLOAD_FOLDER"], path)
+    app.mount("/doc", StaticFiles(directory=DOCAT_UPLOAD_FOLDER), name="docs")