Merge pull request #237 from lsst-sqre/tickets/DM-42730

tickets/DM-42730: modernize Checkerboard and move it off Roundtable

.github/workflows/ci.yaml

@@ -23,6 +23,7 @@ jobs:
       matrix:
         python:
           - "3.11"
+          - "3.12"
 
     steps:
       - uses: actions/checkout@v3

.gitignore

@@ -132,3 +132,6 @@ dmypy.json
 
 # pytype static type analyzer
 .pytype/
+
+# Mac desktop
+.DS_Store

.pre-commit-config.yaml

@@ -1,23 +1,17 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
-      - id: check-yaml
+      - id: check-merge-conflict
       - id: check-toml
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: trailing-whitespace
 
-  - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-        additional_dependencies:
-          - toml
-
-  - repo: https://github.com/psf/black
-    rev: 23.3.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.15
     hooks:
-      - id: black
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
 
-  - repo: https://github.com/pycqa/flake8
-    rev: 6.0.0
-    hooks:
-      - id: flake8

CHANGELOG.md

@@ -0,0 +1,62 @@
+# Change log
+
+Checkerboard is versioned with [semver](https://semver.org/). Dependencies are updated to the latest available version during each release. Those changes are not noted here explicitly.
+
+Find changes for the upcoming release in the project's [changelog.d directory](https://github.com/lsst-sqre/checkerboard/tree/main/changelog.d/).
+
+<!-- scriv-insert-here -->
+
+## 0.4.0 (2024-02-08)
+This release drops support for Python 3.9 and 3.10.  Python 3.11 or later is now required.
+
+- Require Python 3.11 or later and drop Python 3.9 and 3.10 support.
+- Rewrite Checkerboard as a [FastAPI](https://fastapi.tiangolo.com/) service.
+- Deploy Checkerboard as a [Phalanx](https://phalanx.lsst.io) service.
+
+## 0.3.1 (2021-03-01)
+
+This release drops support for Python 3.7 and 3.8.
+Python 3.9 or later is now required.
+
+- Require Python 3.9 and drop Python 3.7 and 3.8 support.
+- Add security hardening to the Kustomize Kubernetes manifest.
+- Honor logging configuration when logging Slack mapper actions.
+- Update all dependencies.
+
+## 0.3.0 (2020-03-04)
+
+With this release, Checkerboard has been rewritten as an [aiohttp](https://docs.aiohttp.org/en/stable/>) application based on the [Safir](https://safir.lsst.io) framework.
+The configuration and routes have all changed in this release.
+
+- `/checkerboard` now returns only application metadata.
+    For a list of all mappings, use `/checkerboard/slack`.
+- Routes no longer support appending trailing slashes.
+- The application now requires only one Slack token, which is set using the `CHECKERBOARD_SLACK_TOKEN` environment variable.
+- Change the environment variable `CHECKERBOARD_USER` to `CHECKERBOARD_USERNAME` and `CHECKERBOARD_PW` to `CHECKERBOARD_PASSWORD`.
+- The expected structure of the Kubernetes secret has changed.
+    See `manifests/secret.template.yaml` for the new structure.
+
+## 0.2.0 (2020-02-19)
+
+With this release, the package is now named Checkerboard.
+See `README.md` for more information about the naming choice.
+
+- Rename the package in multiple places.
+- Rename the Python package from `uservice_ghslacker` to `checkerboard`.
+- Change environment variables controlling application settings to start with `CHECKERBOARD_` instead of `GHSLACKER_`.
+- Change all routes from `/ghslacker` to `/checkerboard`.
+- Base the Docker container on python:3.7 instead of centos:7.
+    This saves some setup work and is based on a standard buildpack-deps container.
+- Add a trivial test so that the test suite can run.
+    More extensive tests will be added later after a refactoring.
+
+## 0.1.1 (2020-02-14)
+
+- Bump dependency on sqre-apikit to pick up a fix for a conflict between older Flask and new werkzeug.
+
+## 0.1.0 (2020-02-13)
+
+- userve-ghslacker can now be deployed through Kustomize.
+    The base is located at ``/manifests/base``.
+    This means that you can incorporate this application into a specific Kustomize-based application (such as one deployed by Argo CD) with a URL such as `github.com/lsst-sqre/uservice-ghslacker.git//manifests/base?ref=0.1.0`.
+    There is a *separate* template for the Secret resource expected by the deployment at `/manifests/secret.template.yaml`.

Dockerfile

@@ -64,4 +64,6 @@ USER appuser
 
 EXPOSE 8080
 
-ENTRYPOINT ["checkerboard", "run", "--port", "8080"]
+COPY scripts/start.sh /start.sh
+
+CMD ["/start.sh"]

README.md

@@ -0,0 +1,61 @@
+# Checkerboard
+
+Checkerboard is a [FastAPI](https://fastapi.tiangolo.com/) service to map user identities between systems with their own concepts of identity.
+Currently, only mapping between Slack users and GitHub users is supported.
+Slack users are associated with GitHub users via a custom field in the Slack profile.
+The default field name is "GitHub Username".
+
+This is an Rubin Observatory DM SQuaRE Roundtable microservice, developed with the [Safir](https://safir.lsst.io) framework.
+
+## Usage
+
+Use ``checkerboard run`` to start the service.
+By default, it will run on port 8080.
+This can be changed with the ``--port`` option.
+
+## Configuration
+
+The following environment variables must be set in Checkerboard's runtime environment.
+
+* `CHECKERBOARD_USERNAME`: The HTTP Basic Authentication user expected
+* `CHECKERBOARD_PASSWORD`: The HTTP Basic Authentication password expected
+* `CHECKERBOARD_SLACK_TOKEN`: Slack bot token with `users:read` and `users.profile:read` scopes
+* `CHECKERBOARD_REDIS_PASSWORD`: The password for Checkerboard to communicate with its Redis instance.
+
+The following environment variables may optionally be set to change default behavior.
+
+* `SAFIR_PROFILE`: Set to `production` to enable production logging
+* `SAFIR_LOG_LEVEL`: Set to `DEBUG`, `INFO`, `WARNING`, or `ERROR` to change the log level.
+    The default is `INFO`.
+* `CHECKERBOARD_PROFILE_FIELD`: The name of the custom field in Slack from which to obtain the GitHub username.
+    The default is `GitHub Username`.
+* `CHECKERBOARD_REFRESH_INTERVAL`: How frequently (in seconds) to refresh the Slack <-> GitHub mapping.
+    This takes about 10 minutes for 2,000 users, so do not lower this too much.
+    The default is 3600 (one hour).
+
+## Routes
+
+Checkerboard has a `/` health-check route exposing metadata; `/checkerboard/` gives the same data under the `_metadata` key.  This does not require authentication.
+
+It has the standard set of documentation endpoints at `/checkerboard/docs`, `/checkerboard/redoc`, and `/checkerboard/openapi.json`.  These routes, too, do not require authentication.
+
+All other requests must be authenticated with HTTP Basic Authentication using the username and password defined by the ``CHECKERBOARD_USERNAME`` and ``CHECKERBOARD_PASSWORD`` environment variables.  The routes and their expected parameters are available at the documentation endpoints.  They are as follows:
+
+* `/checkerboard/slack`: Returns all known Slack to GitHub user mappings.
+    The Slack user ID is the key, and the lowercased representation of the GitHub username (or, more generally, the contents of the field specified in the service) is the value.
+
+* `/checkerboard/slack/<user>`: Returns a JSON object whose key is `<user>`, which is a Slack `id` (*not* a display name), and whose value is the corresponding GitHub user.
+      Returns a 404 if either the user ID is not found, or there is no corresponding GitHub user.
+
+* `/checkerboard/github/<user>`: Returns a JSON object whose value is ``<user>`` and whose key is the corresponding Slack user `id`.
+    Returns a 404 if there is no GitHub username `<user>` (not case-sensitive) mapped to a Slack user.
+    The GitHub username in the returned value will always have the same capitalization as the query, regardless of the actual username at GitHub.
+
+## Deployment
+
+Checkerboard is deployed as a standard [Phalanx](https://phalanx.lsst.io) application.
+
+## Naming
+
+Checkerboard is a (very simple) federated identity service used by the SQuaRE tem at the Rubin Observatory.
+A checkerboard is a federation of squares.

changelog.d/_template.md.jinja

@@ -0,0 +1,7 @@
+<!-- Delete the sections that don't apply -->
+{%- for cat in config.categories %}
+
+### {{ cat }}
+
+-
+{%- endfor %}