Implement health checks and graceful termination (#1)

* Implement health checks and graceful termination * Add GitHub workflows * Rename endpoint functions * Add docstrings to health check functions * Add badges to README * Add manual * Add both stable/dev docs badges * Specify YAS formatting * fixup! Rename endpoint functions * Reference localhost more * Document keyword `set_entrypoint` * Comment on dead code * Log invalid graceful terminator requests * Add argument documentation to `K8sDeputy.serve!` * Add quickstart guide * Use default K8sDeputy.jl port in quickstart * Formatting * Add LICENSE file * Documentation corrections Co-authored-by: Glenn Moynihan <[email protected]> * Indicate mutating health functions * Rename `entrypoint_pid(::Integer)` to `set_entrypoint_pid` * Document custom exit status * Fix note syntax Co-authored-by: Dave Kleinschmidt <[email protected]> * Add test for gracefully terminating multiple Julia processes * Cross reference graceful termination --------- Co-authored-by: Glenn Moynihan <[email protected]> Co-authored-by: Dave Kleinschmidt <[email protected]>
beacon-biosignals · Mar 8, 2024 · e0f8b13 · e0f8b13
1 parent bc40e38
commit e0f8b13
Show file tree

Hide file tree

Showing 23 changed files with 1,217 additions and 1 deletion.
diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml
@@ -0,0 +1 @@
+style = "yas"
diff --git a/.github/workflows/CI.yaml b/.github/workflows/CI.yaml
@@ -0,0 +1,59 @@
+---
+name: CI
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags: ["*"]
+    paths:
+      - "src/**"
+      - "test/**"
+      - "Project.toml"
+      - ".github/workflows/CI.yaml"
+  pull_request:
+    paths:
+      - "src/**"
+      - "test/**"
+      - "Project.toml"
+      - ".github/workflows/CI.yaml"
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.runs-on }} - ${{ matrix.arch }} - ${{ matrix.threads}} threads
+    # These permissions are needed to:
+    # - Delete old caches: https://github.com/julia-actions/cache#cache-retention
+    permissions:
+      actions: write
+      contents: read
+    runs-on: ${{ matrix.runs-on }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - "1.6"  # Earliest version of Julia that the package is compatible with
+          - "1"    # Latest Julia release
+        runs-on:
+          - ubuntu-latest
+        arch:
+          - x64
+        threads:
+          - 1
+    env:
+      JULIA_NUM_THREADS: ${{ matrix.threads }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v3
+        with:
+          file: lcov.info
diff --git a/.github/workflows/DocPreviewCleanup.yaml b/.github/workflows/DocPreviewCleanup.yaml
@@ -0,0 +1,39 @@
+---
+# remove PR previews once they're merged
+# <https://juliadocs.github.io/Documenter.jl/dev/man/hosting/#gh-pages-Branch>
+name: Doc Preview Cleanup
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      PR: ${{ github.event.number }}
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          preview_dir="previews/PR${PR?}"
+          if [ -d "${preview_dir}" ]; then
+              # Delete preview directory created by this PR
+              git rm -rf "${preview_dir}"
+
+              # Commit the removed preview directories and truncate history
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "squash history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
diff --git a/.github/workflows/Documenter.yaml b/.github/workflows/Documenter.yaml
@@ -0,0 +1,58 @@
+---
+name: Documenter
+on:
+  workflow_dispatch:
+  push:
+    tags: ["*"]
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "Project.toml"
+      - ".github/workflows/Documenter.yaml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "Project.toml"
+      - ".github/workflows/Documenter.yaml"
+      - ".github/workflows/DocPreviewCleanup.yaml"
+jobs:
+  docs:
+    name: Build
+    # These permissions are needed to:
+    # - Delete old caches: https://github.com/julia-actions/cache#usage
+    permissions:
+      actions: write
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: "1"
+          show-versioninfo: true
+      - uses: julia-actions/cache@v1
+      - name: Install dependencies
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+      - name: Build docs
+        uses: julia-actions/julia-docdeploy@v1
+        with:
+          install-package: false  # Avoid instantiating twice
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Preview URL
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          repo_owner="${repo%/*}"  # e.g. JuliaLang
+          repo_name="${repo#*/}"  # e.g. Example.jl
+          echo ":books: Documentation preview available at:" | tee -a "$GITHUB_STEP_SUMMARY"
+          echo "<https://${repo_owner}.github.io/${repo_name}/previews/PR${PR}>" | tee -a "$GITHUB_STEP_SUMMARY"
+        env:
+          repo: ${{ github.repository }}  # e.g. JuliaLang/Example.jl
+          PR: ${{ github.event.number }}
diff --git a/.github/workflows/FormatCheck.yaml b/.github/workflows/FormatCheck.yaml
@@ -0,0 +1,46 @@
+---
+name: Format Check
+on:
+  push:
+    branches:
+      - main
+    tags: ["*"]
+    paths:
+      - "**/*.jl"
+      - ".github/workflows/FormatCheck.yaml"
+  pull_request:
+    paths:
+      - "**/*.jl"
+      - ".github/workflows/FormatCheck.yml"
+jobs:
+  format-check:
+    name: Julia
+    # These permissions are needed to:
+    # - Delete old caches: https://github.com/julia-actions/cache#usage
+    # - Post formatting suggestions: https://github.com/reviewdog/action-suggester#required-permissions
+    permissions:
+      actions: write
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: "1"
+      - uses: julia-actions/cache@v1
+      - name: Install JuliaFormatter
+        shell: julia --project=@format --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.add(PackageSpec(; name="JuliaFormatter", version="1"))
+      - name: Check formatting
+        shell: julia --project=@format --color=yes {0}
+        run: |
+          using JuliaFormatter
+          format("."; verbose=true) || exit(1)
+      # Add formatting suggestions to non-draft PRs even if when "Check formatting" fails
+      - uses: reviewdog/action-suggester@v1
+        if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.draft == false }}
+        with:
+          tool_name: JuliaFormatter
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+docs/build
+Manifest.toml
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Beacon Biosignals, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/Project.toml b/Project.toml
@@ -0,0 +1,26 @@
+name = "K8sDeputy"
+uuid = "2481ae95-212f-4650-bb21-d53ea3caf09f"
+authors = ["Beacon Biosignals, Inc"]
+version = "0.1.0"
+
+[deps]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
+Mocking = "78c3b35d-d492-501b-9361-3d52fe80e533"
+Sockets = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[compat]
+Aqua = "0.7"
+Dates = "1"
+HTTP = "1"
+Mocking = "0.7"
+Sockets = "1"
+Test = "1"
+julia = "1.6"
+
+[extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Aqua", "Test"]
diff --git a/README.md b/README.md
@@ -1,2 +1,8 @@
 # K8sDeputy.jl
-Provides K8s health checks and graceful termination support on behalf of Julia services
+
+[![CI](https://github.com/beacon-biosignals/K8sDeputy.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/beacon-biosignals/K8sDeputy.jl/actions/workflows/CI.yml)
+[![Code Style: YASGuide](https://img.shields.io/badge/code%20style-yas-violet.svg)](https://github.com/jrevels/YASGuide)
+[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://beacon-biosignals.github.io/K8sDeputy.jl/stable)
+[![Dev Documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://beacon-biosignals.github.io/K8sDeputy.jl/dev)
+
+Provides K8s health checks and graceful termination support on behalf of Julia services.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+K8sDeputy = "2481ae95-212f-4650-bb21-d53ea3caf09f"
+
+[compat]
+Documenter = "1.0.0"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,18 @@
+using K8sDeputy
+using Documenter
+
+pages = ["Home" => "index.md",
+         "Quickstart" => "quickstart.md",
+         "Health Checks" => "health_checks.md",
+         "Graceful Termination" => "graceful_termination.md",
+         "API" => "api.md"]
+
+makedocs(; modules=[K8sDeputy],
+         format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true"),
+         sitename="K8sDeputy.jl",
+         authors="Beacon Biosignals",
+         pages)
+
+deploydocs(; repo="github.com/beacon-biosignals/K8sDeputy.jl.git",
+           push_preview=true,
+           devbranch="main")
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -0,0 +1,10 @@
+# API
+
+```@docs
+Deputy
+K8sDeputy.serve!
+readied!
+shutdown!
+graceful_terminator
+graceful_terminate
+```