feat: Initial project structure

Author: Alan Christie

.github/workflows/build.yaml

@@ -0,0 +1,47 @@
+---
+name: build
+
+# ---------------
+# Control secrets
+# ---------------
+#
+# At the GitHub 'organisation' or 'project' level you are expected to
+# have the following GitHub 'Repository Secrets' defined
+# (i.e. via 'Settings -> Secrets'): -
+#
+# (none)
+#
+# -----------
+# Environment (GitHub Environments)
+# -----------
+#
+# (none)
+
+on:
+  push:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Inject slug/short variables
+      uses: rlespinasse/github-slug-action@v5
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Lint Dockerfile
+      uses: hadolint/hadolint-action@v3.1.0
+      with:
+        dockerfile: Dockerfile
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Run pre-commit (all files)
+      run: |
+        pip install --requirement build-requirements.txt
+        pre-commit run --all-files
+    - name: Docker build
+      uses: docker/build-push-action@v6
+      with:
+        context: .
+        tags: ${{ github.repository_owner }}/squonk2-fastapi-ws-event-stream:${{ env.GITHUB_REF_SLUG }}

.pre-commit-config.yaml

@@ -0,0 +1,63 @@
+---
+minimum_pre_commit_version: 4.0.0
+
+repos:
+
+# commit-msg hooks
+# ----------
+
+# Conventional Commit message checker (commitizen)
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: v4.1.0
+  hooks:
+  - id: commitizen
+    stages:
+    - commit-msg
+
+# pre-commit hooks
+# ----------
+
+# Hooks that actively "change" files (formatters etc.)
+# ----------------------------------
+
+# Standard pre-commit rules
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: check-case-conflict
+  - id: check-docstring-first
+  - id: check-executables-have-shebangs
+  - id: check-shebang-scripts-are-executable
+  - id: detect-private-key
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+    args:
+    - --markdown-linebreak-ext=md
+
+# isort (in black-compatibility mode)
+- repo: https://github.com/pycqa/isort
+  rev: 6.0.0
+  hooks:
+  - id: isort
+    args:
+    - --profile
+    - black
+    - --filter-files
+
+# Black (uncompromising) Python code formatter
+- repo: https://github.com/psf/black
+  rev: 25.1.0
+  hooks:
+  - id: black
+    args:
+    - --target-version
+    - py312
+
+# pylint
+- repo: https://github.com/pycqa/pylint
+  rev: v3.3.4
+  hooks:
+  - id: pylint
+    args:
+    - --disable=import-error
+    - --py-version=3.12

Dockerfile

@@ -0,0 +1,72 @@
+# The default base image
+ARG from_image=python:3.12.9-slim
+ARG image_tag=0.0.0
+FROM ${from_image} AS python-base
+
+# Labels
+LABEL maintainer='Alan Christie <achristie@informaticsmatters.com>'
+
+# Force the binary layer of the stdout and stderr streams
+# to be unbuffered
+ENV PYTHONUNBUFFERED 1
+
+# Base directory for the application
+# Also used for user directory
+ENV APP_ROOT /home/es
+
+WORKDIR ${APP_ROOT}
+
+##################################################################
+#
+# Second stage, poetry installation.
+#
+##################################################################
+FROM python-base AS poetry-base
+ARG image_tag
+ARG POETRY_VERSION=1.8.5
+
+RUN pip install --no-cache-dir poetry==${POETRY_VERSION}
+
+WORKDIR /
+COPY poetry.lock pyproject.toml /
+
+# Despite letting poetry create virtualenv here, we're not using it in
+# the final container, we just let poetry install the packages and
+# copy them later. POETRY_VIRTUALENVS_IN_PROJECT flag tells poetry to
+# create the venv to project's directory (.venv). This way the
+# location is predictable
+RUN POETRY_VIRTUALENVS_IN_PROJECT=true poetry install --no-root --only main --no-directory
+
+##################################################################
+#
+# Final stage.
+# Only copy the venv with installed packages and point paths to it
+#
+##################################################################
+FROM python-base AS final
+ARG image_tag
+
+COPY --from=poetry-base /.venv /.venv
+
+ENV PYTHONPATH="${PYTHONPATH}:/.venv/lib/python3.13/site-packages/"
+ENV PATH=/.venv/bin:$PATH
+ENV IMAGE_TAG=${image_tag}
+
+COPY app/ ./app/
+COPY docker-entrypoint.sh .
+
+# Probes...
+COPY probes/*.sh .
+# Kubernetes lifecycle hooks...
+COPY hooks/*.sh .
+
+# Create a base directory for file-based logging
+WORKDIR /log
+
+# Switch to container user
+ENV HOME ${APP_ROOT}
+WORKDIR ${APP_ROOT}
+USER root
+
+# Start the application
+CMD ./docker-entrypoint.sh

README.md

@@ -1,2 +1,42 @@
-# squonk2-fastapi-ws-event-stream
-A FastAPI (Python) implementation of the Squonk2 (AS) Event Streaming service
+# Squonk2 FastAPI WebSocket Event Stream
+A FastAPI (Python) implementation of the Squonk2 (AS) Event Streaming service.
+
+This repository is responsible for the container image that implements
+the even-streaming service of the Squonk2 AS platform and is deployed to the
+Namespace of the AS to service internal requests from the API to create, delete
+and connect to the internal messaging bus to stream events to a client.
+
+The implementation is based on Python and the FastAPI framework, offering an _internal_
+API for use by the AS and a _public_ web-socket API for clients to connect to.
+
+## Contributing
+The project uses: -
+
+- [pre-commit] to enforce linting of files prior to committing them to the
+  upstream repository
+- [Commitizen] to enforce a [Conventional Commit] commit message format
+- [Black] as a code formatter
+- [Poetry] as a package manager (for the b/e)
+
+You **MUST** comply with these choices in order to  contribute to the project.
+
+To get started review the pre-commit utility and the conventional commit style
+and then set-up your local clone by following the **Installation** and
+**Quick Start** sections: -
+
+    poetry shell
+    poetry install --with dev
+    pre-commit install -t commit-msg -t pre-commit
+
+Now the project's rules will run on every commit, and you can check the
+current health of your clone with: -
+
+    pre-commit run --all-files
+
+---
+
+[black]: https://black.readthedocs.io/en/stable
+[commitizen]: https://commitizen-tools.github.io/commitizen/
+[conventional commit]: https://www.conventionalcommits.org/en/v1.0.0/
+[pre-commit]: https://pre-commit.com
+[poetry]: https://python-poetry.org/

app/__init__.py

@@ -0,0 +1,31 @@
+"""The entrypoint for the Squonk2 FastAPI WebSocket service."""
+
+from fastapi import FastAPI
+
+# Public (event-stream) and internal (REST) services
+app_es = FastAPI()
+app_internal = FastAPI()
+
+
+# Endpoints for the 'public-facing' event-stream web-socket API ------------------------
+
+
+@app_es.get("/event-stream/")
+def event_stream():
+    """Read from the event-stream."""
+    return {"message": "MESSAGE"}
+
+
+# Endpoints for the 'internal' event-stream management API -----------------------------
+
+
+@app_internal.post("/event-stream/")
+def post_es():
+    """Create a new event-stream."""
+    return {"id": 1}
+
+
+@app_internal.delete("/event-stream/{es_id}")
+def delete_es(es_id: int):
+    """Destroys an existing event-stream."""
+    return {"message": f"Destroy ES {es_id}"}

app/app.py

@@ -0,0 +1,11 @@
+---
+services:
+
+  es:
+    build:
+      context: .
+    image: informaticsmatters/squonk2-fastapi-ws-event-stream:latest
+    container_name: es
+    ports:
+    - '8080:8080'
+    - '8081:8081'

docker-compose.yml

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+#set -e
+
+# Run the container using both the customer-facing WebSocket service
+# and the internal REST endpoint.
+# Done my simply launching two uvicorn instances in parallel.
+echo "+> Launching uvicorn..."
+uvicorn app.app:app_p --reload --host 0.0.0.0 --port 8080 & \
+    uvicorn app.app:app_i --reload --host 0.0.0.0 --port 8081

docker-entrypoint.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# A container lifecycle hook.
+# Called from Kubernetes when the corresponding container is required to stop.
+# See https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination
+
+# Here, we create the file '${APP_ROOT}/given.poison'.
+touch ${APP_ROOT}/given.poison
+
+# It's the API Pod - there's no need to wait for anything.
+# The Pod will be set to TERMINATED and no new traffic will be presented to it.
+# We rely on the Pod's 'terminationGracePeriodSeconds' to actually terminate the Pod.