Release/v1.61.0

.github/workflows/go.yml

@@ -10,17 +10,20 @@ on:
     branches:
       - main
       - development
+    # Kept on `push` only. A docs merge cannot change Go coverage or lint
+    # results, and re-running the pipeline on development would publish a
+    # duplicate qlty point via upload_coverage and queue behind other merges
+    # (push runs are deliberately never cancelled — see the concurrency note
+    # below). The gating that matters happens on `pull_request`, which
+    # deliberately has no filter so docs-only PRs run the full required set.
     paths-ignore:
-      - 'docs/**'  # Ignore changes to docs folder
+      - 'docs/**'
       - '**/*.md'
   # Run on pull requests to main or development branches
   pull_request:
     branches:
       - main
       - development
-    paths-ignore:
-      - 'docs/**'  # Ignore changes to docs folder
-      - '**/*.md'
 
 # One in-flight run per ref. Pushing twice to a PR branch otherwise starts a
 # second full 14-job matrix — including the Kafka/Redis/MySQL services and the
@@ -167,11 +170,16 @@ jobs:
       # Run it explicitly (same pattern as Zipkin above) and wait for readiness.
       - name: Start MinIO
         run: |
-          # Pinned by digest now that this step is required: an unexpected image
+          # Pulled from quay.io, not Docker Hub: docker.io/minio/minio is no
+          # longer publicly pullable ("pull access denied ... repository does not
+          # exist or may require 'docker login'"), for every tag and for the
+          # digest below. quay.io/minio/minio carries the identical manifest list
+          # — same digest — so this is a registry change and not an image change.
+          # Pinned by digest because this step is required: an unexpected image
           # change can't silently alter the integration guard for #3804.
           docker run -d --name minio -p 9000:9000 \
             -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin \
-            minio/minio:RELEASE.2025-09-07T16-13-09Z@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e \
+            quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e \
             server /data
           for i in $(seq 1 30); do
             if curl -fs http://localhost:9000/minio/health/live >/dev/null; then
@@ -283,10 +291,19 @@ jobs:
             set -eo pipefail
             export APP_ENV=test
 
-            # Run tests for root gofr package
+            # Run tests for root gofr package.
+            #
+            # `-coverpkg=./pkg/gofr/...`, not `./pkg/gofr`: the narrow form
+            # instruments only the 29 top-level pkg/gofr/*.go files, so every
+            # in-repo sub-package — http, http/middleware, container, service,
+            # logging, cmd, migration, rbac, datasource/sql, datasource/redis
+            # and the rest — was absent from the published figure even though
+            # its tests run here on every push. The narrow glob measured 1,848
+            # statements; the tree measures 10,482, and the figure went from
+            # 86.5% to 90.0% without a new test being written (#4202).
             exit_code=0
             go test -v -short -covermode=atomic \
-              -coverpkg=./pkg/gofr -coverprofile=gofr_only.cov ./pkg/gofr || exit_code=$?
+              -coverpkg=./pkg/gofr/... -coverprofile=root_pkg.cov ./pkg/gofr || exit_code=$?
             if [ $exit_code -eq 2 ]; then
               echo "::error::Panic detected in root gofr package tests"
               exit 2
@@ -295,10 +312,13 @@ jobs:
               exit $exit_code
             fi
 
-            # Run tests for sub-packages
+            # Run tests for sub-packages. Same widening as above; the profile
+            # name says sub-packages because these are packages of this module,
+            # not the pkg/gofr/datasource/* submodules (those are separate Go
+            # modules, covered by Submodule-Unit-Testing).
             exit_code=0
             go test -v -covermode=atomic \
-              -coverpkg=./pkg/gofr -coverprofile=submodules.cov ./pkg/gofr/... || exit_code=$?
+              -coverpkg=./pkg/gofr/... -coverprofile=sub_pkgs.cov ./pkg/gofr/... || exit_code=$?
             if [ $exit_code -eq 2 ]; then
               echo "::error::Panic detected in gofr sub-packages tests"
               exit 2
@@ -307,9 +327,28 @@ jobs:
               exit $exit_code
             fi
 
-            # Combine coverage profiles
+            # Combine coverage profiles.
+            #
+            # `/mock_` strips generated gomock files. `/testutil/` strips the
+            # test helper package, which the widened -coverpkg would otherwise
+            # admit: it is scaffolding for tests, not shipped behaviour, and at
+            # 98% it flatters the numerator the same way the mocks would.
+            #
+            # The awk merges duplicate blocks. Under a multi-package -coverpkg
+            # every block is emitted once per test binary, so a plain
+            # concatenation here is 31 copies of the same 12k blocks: 21 MB of
+            # profile to upload, download and hand to qlty. Keyed by block
+            # position, statement count carried through, execution counts
+            # summed — which is what merging two profiles of the same code
+            # means. `go tool cover` reaches the same percentage either way
+            # (it resolves duplicates itself); this is about the artifact, and
+            # about a profile a human can read.
             echo "mode: atomic" > profile.cov
-            grep -h -v "mode:" gofr_only.cov submodules.cov | grep -v '/mock_' >> profile.cov
+            grep -h -v "mode:" root_pkg.cov sub_pkgs.cov \
+              | grep -v '/mock_' \
+              | grep -v '/testutil/' \
+              | awk '{stmts[$1] = $2; count[$1] += $3} END {for (blk in stmts) print blk, stmts[blk], count[blk]}' \
+              | sort >> profile.cov
 
             # Show coverage summary
             go tool cover -func profile.cov
@@ -447,8 +486,25 @@ jobs:
               # is checked without mutation in the code_quality job instead.
               go mod download
 
-              # Run tests with a focus on failed tests first
-              go test ./... -v -short -coverprofile="${module_name}.cov" -coverpkg=./...
+              # NOTE: this whole block is the single-quoted payload of the
+              # `bash -c` above, so nothing in here may contain an apostrophe —
+              # not even inside a comment. One in a comment closes the quote and
+              # the runner fails with a syntax error before any test runs.
+              #
+              # Deliberately NOT `-short`. It does not merely shorten these
+              # suites, it deletes whole test functions from the coverage figure:
+              # the mtest harness shipped by the mongo driver calls t.Skip with
+              # "skipping mtest integration test in short mode" even under
+              # ClientType of mtest.Mock, which needs no server and no network.
+              # Ten test functions covering every mongo CRUD path were being
+              # skipped, so pkg/gofr/datasource/mongo reported 27.2% instead of
+              # 87.7% for tests that already exist and run in 1.4s.
+              #
+              # Measured across all 27 submodules: mongo is the only one whose
+              # figure changes at all and the only one with any testing.Short
+              # gating, and all 27 pass either way. Dropping the flag changes
+              # only what mtest was hiding.
+              go test ./... -v -coverprofile="${module_name}.cov" -coverpkg=./...
 
               # Copy coverage file to the coverage_reports directory
               cp "${module_name}.cov" "$COVERAGE_DIR/"

.github/workflows/typos.yml

@@ -27,4 +27,4 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@v7
       - name: typos-action
-        uses: crate-ci/typos@4d9c206a77c041268485162b8e2579ad7a5cb9a3 # v1.50.0
+        uses: crate-ci/typos@d43b6c087ac471e2ea7b8af622ff15f05c0c365b # v1.50.1

.github/workflows/website-pr.yml

@@ -0,0 +1,98 @@
+name: Website Build Check
+permissions:
+  contents: read
+
+# Why this exists
+# ---------------
+# `docs/Dockerfile` overlays this repo's docs/ onto the gofr-dev/website
+# source bundle and runs `npm run build` (Next.js static export). Until now
+# that build was only ever exercised by website-stage.yml, which triggers on
+# `push: development` — i.e. *after* a docs PR is merged. A broken
+# navigation.js, a malformed events.json/team.json, or an MDX file next can't
+# parse therefore reached development and was discovered by a failed stage
+# deploy rather than by the PR that caused it.
+#
+# This runs the same two builds at PR time and stops there.
+on:
+  pull_request:
+    branches:
+      - main
+      - development
+    # Everything docs/Dockerfile consumes lives under docs/ — including the
+    # Dockerfile itself. A PR that touches no docs/ file cannot change the
+    # website build, so it is not worth ~8 minutes of runner time.
+    #
+    # NOTE: because of this filter the check does not report on non-docs PRs,
+    # so it cannot be made a *required* status check without deadlocking them.
+    # Gate it in branch protection only if this filter is removed first.
+    paths:
+      - 'docs/**'
+      - '.github/workflows/website-pr.yml'
+  workflow_dispatch:
+
+# Deliberately the opposite of website-prod.yml / website-stage.yml, which set
+# `cancel-in-progress: false` because a half-finished *deploy* is worse than a
+# queued one. This workflow deploys nothing, so a superseded run is pure waste.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  website_build:
+    name: 🌐 Website Build
+    runs-on: ubuntu-latest
+    # Two docker builds, each doing its own npm install. website-stage.yml
+    # budgets 45m for the same pair plus yarn install, refresh-data and a
+    # registry push; without those 30m is ample.
+    timeout-minutes: 30
+    steps:
+      - name: Checkout framework code
+        uses: actions/checkout@v7
+
+      # gofr-dev/website is public, so the default GITHUB_TOKEN is enough and
+      # this step works on pull requests from forks.
+      #
+      # fetch-depth is left at the default 1, unlike website-stage.yml: the
+      # full history there is only needed by utils/generate-doc-mtimes.mjs,
+      # which runs as part of `yarn refresh-data` — a step this workflow
+      # deliberately skips (see below).
+      - name: Checkout website source
+        uses: actions/checkout@v7
+        with:
+          repository: gofr-dev/website
+          ref: main
+          path: website-src
+
+      # No `yarn refresh-data` here, on purpose. It is `continue-on-error: true`
+      # in website-stage.yml — i.e. already not load-bearing for build success —
+      # and each of its scripts falls back to the snapshot committed under
+      # src/data. Those snapshots are exactly what this build uses. Skipping it
+      # keeps the check hermetic (no GitHub API calls, nothing to rate-limit)
+      # and removes the need for Node on the runner: both npm installs happen
+      # inside the docker builds below.
+
+      # Stage 1: the website "shell" — source + node_modules + npm. Identical
+      # invocation to website-stage.yml, including `--target builder`: the
+      # website Dockerfile's final stage is nginx and has no npm, so the
+      # framework's docs/Dockerfile could not run `npm run build` against it.
+      #
+      # Tagged ghcr.io/gofr-dev/website:stage for the *local* daemon only, so
+      # that docs/Dockerfile's `FROM ghcr.io/gofr-dev/website:${WEBSITE_TAG}`
+      # resolves here instead of pulling. Nothing is pushed.
+      - name: Build website source-bundle
+        run: |
+          docker build \
+            --target builder \
+            -t ghcr.io/gofr-dev/website:stage \
+            -f ./website-src/Dockerfile \
+            ./website-src/
+
+      # Stage 2: the actual check. Overlays this PR's docs/ and runs
+      # `npm run build`. This is the step that fails on broken docs.
+      - name: Build framework docs image
+        run: |
+          docker build \
+            --build-arg WEBSITE_TAG=stage \
+            -t gofr-website:pr \
+            -f ./docs/Dockerfile \
+            .

.github/workflows/website-prod.yml

@@ -19,8 +19,9 @@ env:
   APP_NAME: gofr-website
   WEBSITE_REGISTRY: ghcr.io
   GAR_PROJECT: raramuri-tech
-  GAR_REGISTRY: kops-dev
-  CLUSTER_NAME: raramuri-tech
+  GAR_REGISTRY: zopdev
+  CLUSTER_NAME: zopdev-tech
+  CLUSTER_REGION: asia-south1
   CLUSTER_PROJECT: raramuri-tech
   NAMESPACE: gofr-dev
   NAMESPACE_STAGE: gofr-dev-stg
@@ -85,7 +86,7 @@ jobs:
       - name: Login to GAR
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
-          registry: us-central1-docker.pkg.dev
+          registry: asia-south1-docker.pkg.dev
           username: _json_key
           password: ${{ secrets.GOFR_WEBSITE_GOFR_DEV_DEPLOYMENT_KEY }}
 
@@ -123,15 +124,15 @@ jobs:
         run: |
           docker build \
             --build-arg WEBSITE_TAG=latest \
-            -t us-central1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }} \
+            -t asia-south1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }} \
             -f ./docs/Dockerfile \
             .
 
       - name: Push framework docs image to GAR
-        run: docker push us-central1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}
+        run: docker push asia-south1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}
 
       - id: output-image
-        run: echo "image=`echo us-central1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}`" >> "$GITHUB_OUTPUT"
+        run: echo "image=`echo asia-south1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}`" >> "$GITHUB_OUTPUT"
 
   deployment:
     runs-on: ubuntu-latest
@@ -154,7 +155,7 @@ jobs:
           credentials_json: ${{ secrets.GOFR_WEBSITE_GOFR_DEV_DEPLOYMENT_KEY }}
 
       - name: Set GCloud Project and Fetch Cluster Credentials
-        run: gcloud container clusters get-credentials ${{ env.CLUSTER_NAME }} --region=us-central1 --project=${{ env.CLUSTER_PROJECT }}
+        run: gcloud container clusters get-credentials ${{ env.CLUSTER_NAME }} --region=${{ env.CLUSTER_REGION }} --project=${{ env.CLUSTER_PROJECT }}
 
       - name: Update Deployment Image
         run: kubectl set image deployment/${{ env.APP_NAME }} ${{ env.APP_NAME }}=${{ env.image }} --namespace ${{ env.NAMESPACE }}

.github/workflows/website-stage.yml

@@ -22,8 +22,9 @@ env:
   APP_NAME: gofr-website
   WEBSITE_REGISTRY: ghcr.io
   GAR_PROJECT: raramuri-tech
-  GAR_REGISTRY: kops-dev
-  CLUSTER_NAME: raramuri-tech
+  GAR_REGISTRY: zopdev
+  CLUSTER_NAME: zopdev-tech
+  CLUSTER_REGION: asia-south1
   CLUSTER_PROJECT: raramuri-tech
   NAMESPACE: gofr-dev
   NAMESPACE_STAGE: gofr-dev-stg
@@ -86,7 +87,7 @@ jobs:
       - name: Login to GAR
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
-          registry: us-central1-docker.pkg.dev
+          registry: asia-south1-docker.pkg.dev
           username: _json_key
           password: ${{ secrets.GOFR_WEBSITE_GOFR_DEV_STG_DEPLOYMENT_KEY }}
 
@@ -129,15 +130,15 @@ jobs:
         run: |
           docker build \
             --build-arg WEBSITE_TAG=stage \
-            -t us-central1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }} \
+            -t asia-south1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }} \
             -f ./docs/Dockerfile \
             .
 
       - name: Push framework docs image to GAR
-        run: docker push us-central1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}
+        run: docker push asia-south1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}
 
       - id: output-image
-        run: echo "image=`echo us-central1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}`" >> "$GITHUB_OUTPUT"
+        run: echo "image=`echo asia-south1-docker.pkg.dev/${{ env.GAR_PROJECT }}/${{ env.GAR_REGISTRY }}/${{ env.APP_NAME }}:${{ env.TAG }}`" >> "$GITHUB_OUTPUT"
 
   deployment_stage:
     runs-on: ubuntu-latest
@@ -160,7 +161,7 @@ jobs:
           credentials_json: ${{ secrets.GOFR_WEBSITE_GOFR_DEV_STG_DEPLOYMENT_KEY }}
 
       - name: Set GCloud Project and Fetch Cluster Credentials
-        run: gcloud container clusters get-credentials ${{ env.CLUSTER_NAME }} --region=us-central1 --project=${{ env.CLUSTER_PROJECT }}
+        run: gcloud container clusters get-credentials ${{ env.CLUSTER_NAME }} --region=${{ env.CLUSTER_REGION }} --project=${{ env.CLUSTER_PROJECT }}
 
       - name: Update Deployment Image
         run: kubectl set image deployment/${{ env.APP_NAME }} ${{ env.APP_NAME }}=${{ env.image }} --namespace ${{ env.NAMESPACE_STAGE }}

CONTRIBUTING.md

@@ -126,7 +126,7 @@ docker run -it --rm -p 4443:4443 -e STORAGE_EMULATOR_HOST=0.0.0.0:4443 fsouza/fa
       conflict.
 * External Library uses:
     - A little copying is better than a little dependency.
-    - All external dependencies should go through the same careful consideration, we would have done to our own written
+    - All external dependencies should go through the same careful consideration, we would have done for our own written
       code. We need to test the functionality we are going to use from an external library, as sometimes library
       implementation may change.
     - All dependencies must be abstracted as an interface. This will make it easier to switch libraries at later point
@@ -135,7 +135,7 @@ docker run -it --rm -p 4443:4443 -e STORAGE_EMULATOR_HOST=0.0.0.0:4443 fsouza/fa
 
 ### Documentation
 * After adding or modifying existing code, update the documentation too - [development/docs](https://github.com/gofr-dev/gofr/tree/development/docs).
-* When you consider a new documentation page is needed, start by adding a new file and writing your new documentation. Then - add a reference to it in [navigation.js](https://gofr.dev/docs/navigation.js).
+* When you consider a new documentation page is needed, start by adding a new file and writing your new documentation. Then - add a reference to it in [navigation.js](https://github.com/gofr-dev/gofr/blob/development/docs/navigation.js).
 * If needed, update or add proper code examples for your changes.
 * In case images are needed, add it to [docs/public](./docs/public) folder.
 * Make sure you don't break existing links and references.
@@ -144,4 +144,4 @@ docker run -it --rm -p 4443:4443 -e STORAGE_EMULATOR_HOST=0.0.0.0:4443 fsouza/fa
     - Use trailing white space or the <br> HTML tag at the end of the line.
     - Use "`" sign to add single line code and "```" to add multi-line code block.
     - Use relative references to images (in `public` folder as mentioned above.)
-* The [gofr.dev documentation](https://gofr.dev/docs) site is updated upon push to `/docs` path in the repo. Verify your changes are live after next GoFr version.
+* The [gofr.dev documentation](https://gofr.dev/docs) site is updated upon push to `/docs` path in the repo. Verify your changes are live after next GoFr version.