gitlab-labkit 5.1.2 → 5.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d272acd766a807cc483a70b13238a55b91dbffd0de51435c3e754df64562176d
4
- data.tar.gz: 2fbc2ff23bbedca43ef1e5c650b3b6c78a0aa4c7ecfec85fec8eae79ef2d2752
3
+ metadata.gz: a1ef319c707c40ea0cca46358bbacdf18d1068b8f2b778ebc1a1486c33cea1ef
4
+ data.tar.gz: 5cbead469ab098d29afb9dcf2dd97576976a703db93eda7ea337a54bc94fcde9
5
5
  SHA512:
6
- metadata.gz: b469df64589bfe387e3d725d1cc6c6a3e769bc078ccb043b8afdf5f3591bae10a5730ecaa87069b1dc49041f50e6c6e92e145989a2a644e2d2f33fe56abd614f
7
- data.tar.gz: 212bf5a04d9a38b4cd64f6b7319179dba2379f3b89b6b1c6070bf64f9f256ea899f6a02ddc35b271dcb6bfb300100627decd388b7b5e3ae5c45f289d2fdd4bfe
6
+ metadata.gz: 1488c581703cab14db63d485aa2ef3159d8a0cd8449cc34b4aeeb522d97ad2207edb57096f388240cff213ef44aaa925a8219a2464b3ab4054a81b0e8569129a
7
+ data.tar.gz: 4c65d98b9b29084a3c5bdc7e0d9dc166a4708f203840a08180421172f21c0356005641557e46dc14f48fb277570f4bdae041d61072c454dbdfa252e4e8baf5fd
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env bash
2
+ # PostToolUse hook: validate a just-edited file against this repo's pre-commit rules.
3
+ #
4
+ # Runs `pre-commit run --files <file>` on the file that Edit/Write/MultiEdit
5
+ # touched. On failure it prints the output to stderr and exits 2, which feeds the
6
+ # result back to Claude so it can fix the issue. A clean run exits 0 silently.
7
+ set -euo pipefail
8
+
9
+ # no-commit-to-branch guards the branch, not file content, and would fire
10
+ # spuriously (e.g. on jj's detached HEAD). It is irrelevant to file validation.
11
+ export SKIP="no-commit-to-branch"
12
+
13
+ # Run through `mise exec` so mise-managed tools that the hooks rely on
14
+ # (pre-commit, jsonnet-tool, shfmt, ...) are on PATH, matching a normal
15
+ # interactive shell.
16
+ if ! command -v mise >/dev/null 2>&1; then
17
+ echo "pre-commit validation hook requires mise to run." >&2
18
+ exit 1
19
+ fi
20
+
21
+ run() { mise exec -- "$@"; }
22
+
23
+ repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
24
+
25
+ input="$(cat)"
26
+ file="$(printf '%s' "$input" | mise exec jq@1.8 -- jq -r '.tool_input.file_path // empty')"
27
+ [[ -z $file ]] && exit 0
28
+
29
+ # Only validate files that live inside this repository.
30
+ case "$file" in
31
+ "$repo_root"/*) ;;
32
+ *) exit 0 ;;
33
+ esac
34
+
35
+ if ! output="$(cd "$repo_root" && run pre-commit run --files "$file" 2>&1)"; then
36
+ {
37
+ echo "pre-commit reported issues on ${file#"$repo_root"/}:"
38
+ echo
39
+ echo "$output"
40
+ echo
41
+ echo "Re-read the file (hooks such as trailing-whitespace, shfmt, and"
42
+ echo "generate may have rewritten it) and fix any remaining problems."
43
+ } >&2
44
+ exit 2
45
+ fi
46
+
47
+ exit 0
@@ -0,0 +1,15 @@
1
+ {
2
+ "hooks": {
3
+ "PostToolUse": [
4
+ {
5
+ "matcher": "Edit|Write|MultiEdit",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/precommit-validate.sh\""
10
+ }
11
+ ]
12
+ }
13
+ ]
14
+ }
15
+ }
data/.copier-answers.yml CHANGED
@@ -3,7 +3,7 @@
3
3
  # See the project for instructions on how to update the project
4
4
  #
5
5
  # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
6
- _commit: v1.60.0
6
+ _commit: v1.85.0
7
7
  _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
8
8
  ee_licensed: false
9
9
  gitlab_namespace: gitlab-org/ruby/gems
@@ -17,5 +17,6 @@ release_platform: false
17
17
  ruby: true
18
18
  rubygem: true
19
19
  rust: false
20
+ scaffold_target: repo
20
21
  terraform: false
21
22
  truncated_tags: true
data/.gitignore CHANGED
@@ -2,5 +2,4 @@ Gemfile.lock
2
2
  *.gem
3
3
  node_modules
4
4
  .bundle
5
- /.env.sh
6
5
  .idea/
data/.gitlab/CODEOWNERS CHANGED
@@ -1 +1 @@
1
- * @reprazent @andrewn @mkaeppler @ayufan @hmerscher @sankalp_gl @hardikgala @nindurkar @ashs2
1
+ * @reprazent @mkaeppler @ayufan @hmerscher @sankalp_gl @hardikgala @nindurkar @ashs2
@@ -7,22 +7,22 @@
7
7
  image: registry.gitlab.com/gitlab-com/gl-infra/common-ci-tasks-images/duo-workflow-sandbox:latest
8
8
 
9
9
  setup_script:
10
- # Keep mise's data + cache inside the project dir so the `cache:` block below
11
- # can capture them (caching only reliably covers paths under the project dir).
12
- - export MISE_DATA_DIR="${CI_PROJECT_DIR}/.cache/mise/data"
13
- - export MISE_CACHE_DIR="${CI_PROJECT_DIR}/.cache/mise/cache"
14
- - mise trust --yes
15
- - mise install --yes
10
+ # duo-workflow-setup (baked into the image) exports some variables as
11
+ # `export KEY=VALUE` lines on stdout, which we `eval` into the flow's shell.
12
+ - eval "$(/usr/local/bin/duo-workflow-setup)"
16
13
 
17
14
  cache:
18
- # Re-use installed tools as long as the version pins are unchanged.
15
+ # Re-use installed tools and primed pre-commit hooks as long as the version
16
+ # pins / hook config are unchanged.
19
17
  key:
20
18
  files:
21
19
  - .tool-versions
22
20
  - .mise.toml
21
+ - .pre-commit-config.yaml
23
22
  paths:
24
23
  - .cache/mise/data
25
24
  - .cache/mise/cache
25
+ - .cache/pre-commit
26
26
 
27
27
  network_policy:
28
28
  # Allow the Sandbox Runtime's recommended allowlist (GitLab, package
data/.gitlab-ci.yml CHANGED
@@ -79,6 +79,13 @@ conformance-spec:
79
79
  variables:
80
80
  LABKIT_RUBY_SHA: $CI_COMMIT_SHA
81
81
  rules:
82
+ # Renovate's project-token bot cannot create pipelines in labkit-spec
83
+ # (GitLab forbids project bots from joining other projects), so its MRs
84
+ # would hard-fail the bridge. Attempt the trigger but do not block; a
85
+ # human re-running the pipeline gates the MR properly (it runs as them).
86
+ - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $GITLAB_USER_LOGIN =~ /^project_\d+_bot/'
87
+ changes: !reference [.conformance-trigger-paths, changes]
88
+ allow_failure: true
82
89
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
83
90
  changes: !reference [.conformance-trigger-paths, changes]
84
91
  trigger:
data/.mise.toml CHANGED
@@ -7,6 +7,9 @@ legacy_version_file = false
7
7
  # OpenSSL and sidesteps it. This becomes mise's default in 2026.8.0.
8
8
  ruby.compile = false
9
9
 
10
+ # Disable sending anonymous download statistics to mise-versions.jdx.dev.
11
+ use_versions_host_track = false
12
+
10
13
  [tools]
11
14
  # Please continue to use `.tool-versions` to specify tool versions, rather than adding them directly here.
12
15
 
@@ -0,0 +1,101 @@
1
+ import type { Plugin, Hooks } from "@opencode-ai/plugin";
2
+ import { existsSync } from "node:fs";
3
+ import { isAbsolute, join, resolve } from "node:path";
4
+
5
+ /**
6
+ * precommit-validate plugin
7
+ *
8
+ * OpenCode equivalent of the Claude Code PostToolUse hook defined in
9
+ * `.claude/hooks/precommit-validate.sh` (wired up by `.claude/settings.json`).
10
+ *
11
+ * After the agent edits or writes a file, this runs that *same* shell script to
12
+ * validate the file against the repo's pre-commit rules. When pre-commit reports
13
+ * problems, the findings are appended to the tool result so the agent sees them
14
+ * on its next turn and can fix the file. A clean run is silent.
15
+ *
16
+ * The script's exit codes mirror Claude Code's hook contract, so we honour the
17
+ * same distinction here:
18
+ * - 0 = clean or no-op (silent)
19
+ * - 2 = pre-commit reported issues; feed the report back to the model
20
+ * - any other non-zero = non-blocking error (e.g. mise missing); log it for
21
+ * the user but do not nag the model, since it can't fix its environment.
22
+ *
23
+ * The script is reused verbatim: it reads Claude Code's PostToolUse payload on
24
+ * stdin (`{ "tool_input": { "file_path": "..." } }`), so we synthesize that same
25
+ * shape here from OpenCode's tool arguments.
26
+ *
27
+ * Auto-loaded from `.opencode/plugins/`.
28
+ */
29
+
30
+ // OpenCode file-mutating tools, analogous to Claude Code's `Edit|Write|MultiEdit`
31
+ // matcher. Current OpenCode may use `apply_patch` for file edits.
32
+ const FILE_TOOLS = new Set(["apply_patch", "edit", "write"]);
33
+
34
+ const HOOK_SCRIPT = ".claude/hooks/precommit-validate.sh";
35
+
36
+ export const PrecommitValidatePlugin: Plugin = async ({ $, client, directory, worktree }) => {
37
+ const root = worktree || directory;
38
+ const script = join(root, HOOK_SCRIPT);
39
+
40
+ const hooks: Hooks = {
41
+ "tool.execute.after": async (input, output) => {
42
+ if (!FILE_TOOLS.has(input.tool)) return;
43
+ // Inert when the shared script is absent (e.g. loaded in another repo).
44
+ if (!existsSync(script)) return;
45
+
46
+ const filePaths = new Set<string>();
47
+ const filePath: string | undefined = input.args?.filePath;
48
+ if (filePath) filePaths.add(filePath);
49
+
50
+ for (const file of output.metadata?.files ?? []) {
51
+ if (typeof file.filePath === "string") filePaths.add(file.filePath);
52
+ }
53
+
54
+ if (filePaths.size === 0) return;
55
+
56
+ const reports: string[] = [];
57
+
58
+ for (const filePath of filePaths) {
59
+ const absolute = isAbsolute(filePath) ? filePath : resolve(root, filePath);
60
+
61
+ // Same JSON shape Claude Code's PostToolUse hook delivers on stdin. The
62
+ // script itself decides whether the file lives inside the repo.
63
+ const payload = JSON.stringify({ tool_input: { file_path: absolute } });
64
+
65
+ const result = await $`printf '%s' ${payload} | ${script}`
66
+ .cwd(root)
67
+ .nothrow()
68
+ .quiet();
69
+
70
+ if (result.exitCode === 0) continue; // clean / no-op
71
+
72
+ const report =
73
+ result.stderr.toString().trim() || result.stdout.toString().trim();
74
+
75
+ if (result.exitCode === 2) {
76
+ // Blocking: pre-commit reported issues. Surface them to the model by
77
+ // appending to the tool output, the OpenCode equivalent of feeding the
78
+ // hook's stderr back to Claude Code on exit 2.
79
+ if (report) reports.push(report);
80
+ continue;
81
+ }
82
+
83
+ // Non-blocking error (e.g. exit 1 = mise not on PATH). Not something the
84
+ // model can act on, so log it for the user instead of polluting the turn.
85
+ await client.app.log({
86
+ body: {
87
+ service: "precommit-validate",
88
+ level: "warn",
89
+ message: report || `pre-commit validation hook exited ${result.exitCode}`,
90
+ },
91
+ });
92
+ }
93
+
94
+ if (reports.length > 0) {
95
+ output.output += `\n\n<pre-commit-validation>\n${reports.join("\n\n")}\n</pre-commit-validation>`;
96
+ }
97
+ },
98
+ };
99
+
100
+ return hooks;
101
+ };
@@ -15,7 +15,7 @@ repos:
15
15
  - id: check-json
16
16
  - id: detect-private-key
17
17
  - id: mixed-line-ending
18
- args: ["--fix=lf"]
18
+ args: [--fix=lf]
19
19
  - id: no-commit-to-branch
20
20
  args: [--branch, main]
21
21
  - id: pretty-format-json
@@ -36,3 +36,4 @@ repos:
36
36
  - id: gitleaks # Detect hardcoded secrets using Gitleaks
37
37
  - id: editorconfig # Validate text files against .editorconfig
38
38
  - id: yamllint # Validate YAML files using yamllint
39
+ - id: ensure-claude-md
data/.rubocop_todo.yml CHANGED
@@ -151,12 +151,6 @@ Lint/SymbolConversion:
151
151
  - 'spec/labkit/logging/json_logger_spec.rb'
152
152
  - 'spec/support/tracing/shared_examples.rb'
153
153
 
154
- # Offense count: 1
155
- # Configuration parameters: Methods.
156
- Lint/UnexpectedBlockArity:
157
- Exclude:
158
- - 'tools/update-changelog.rb'
159
-
160
154
  # Offense count: 41
161
155
  # This cop supports safe autocorrection (--autocorrect).
162
156
  # Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
@@ -196,13 +190,6 @@ Naming/RescuedExceptionsVariableName:
196
190
  Exclude:
197
191
  - 'lib/labkit/logging/grpc/server_interceptor.rb'
198
192
 
199
- # Offense count: 1
200
- # This cop supports safe autocorrection (--autocorrect).
201
- # Configuration parameters: EnabledForFlattenWithoutParams.
202
- Performance/FlatMap:
203
- Exclude:
204
- - 'tools/update-changelog.rb'
205
-
206
193
  # Offense count: 1
207
194
  Performance/MethodObjectAsBlock:
208
195
  Exclude:
@@ -402,7 +389,7 @@ Style/FileNull:
402
389
  - 'spec/labkit/middleware/sidekiq/user_experience_sli/server_spec.rb'
403
390
  - 'spec/spec_helper.rb'
404
391
 
405
- # Offense count: 8
392
+ # Offense count: 7
406
393
  # This cop supports unsafe autocorrection (--autocorrect-all).
407
394
  # Configuration parameters: EnforcedStyle.
408
395
  # SupportedStyles: always, always_true, never
@@ -415,7 +402,6 @@ Style/FrozenStringLiteralComment:
415
402
  - 'spec/labkit/tracing/rails/active_support/cache_read_instrumenter_spec.rb'
416
403
  - 'spec/labkit/tracing/rails/active_support/cache_write_instrumenter_spec.rb'
417
404
  - 'spec/support/grpc_service/test_services_pb.rb'
418
- - 'tools/update-changelog.rb'
419
405
 
420
406
  # Offense count: 2
421
407
  # This cop supports unsafe autocorrection (--autocorrect-all).
@@ -539,7 +525,7 @@ Style/StringConcatenation:
539
525
  - 'lib/labkit/tracing/jaeger_factory.rb'
540
526
  - 'lib/labkit/tracing/redis/redis_interceptor_helper.rb'
541
527
 
542
- # Offense count: 6
528
+ # Offense count: 4
543
529
  # This cop supports safe autocorrection (--autocorrect).
544
530
  # Configuration parameters: EnforcedStyle.
545
531
  # SupportedStyles: single_quotes, double_quotes
@@ -549,7 +535,6 @@ Style/StringLiteralsInInterpolation:
549
535
  - 'lib/labkit/tracing/grpc/server_interceptor.rb'
550
536
  - 'lib/labkit/tracing/jaeger_factory.rb'
551
537
  - 'spec/labkit/logging/json_logger_spec.rb'
552
- - 'tools/update-changelog.rb'
553
538
 
554
539
  # Offense count: 10
555
540
  # This cop supports safe autocorrection (--autocorrect).
data/AGENTS.md ADDED
@@ -0,0 +1,173 @@
1
+ <<<<<<< before updating
2
+ # AGENTS.md
3
+
4
+ Instructions for AI agents and automated tooling working in this repository.
5
+
6
+ ## Project context
7
+
8
+ LabKit-Ruby (`gitlab-labkit` on RubyGems) is GitLab's Ruby SDK for cross-project infrastructure concerns: request context and correlation, structured logging, tracing, metrics, SLIs, and rate limiting.
9
+ It is consumed by GitLab Rails and other Ruby services, so every public API is a compatibility commitment.
10
+
11
+ It is one of several LabKit SDKs.
12
+ The others are Go ([labkit](https://gitlab.com/gitlab-org/labkit)), Rust ([labkit-rs](https://gitlab.com/gitlab-org/rust/labkit-rs)), and Python ([labkit-python](https://gitlab.com/gitlab-org/labkit-python)).
13
+ Behaviour that services observe, and anything written to a shared store, must be the same in every SDK.
14
+ The contract lives in [labkit-spec](https://gitlab.com/gitlab-org/quality/tooling/labkit-spec), and its conformance harness is the judge.
15
+
16
+ ### Layout
17
+
18
+ One gem, one `Labkit` namespace, one directory per capability under `lib/labkit/`.
19
+ `lib/gitlab-labkit.rb` autoloads each capability unless the table says otherwise, so requiring the gem stays cheap and callers load only what they touch.
20
+
21
+ | Module | Directory | Notes |
22
+ | --- | --- | --- |
23
+ | `Labkit::Context`, `Labkit::Correlation` | `lib/labkit/context.rb`, `lib/labkit/correlation/` | Request context for logs and propagation |
24
+ | `Labkit::Logging` | `lib/labkit/logging/` | Log sanitisation and JSON formatting |
25
+ | `Labkit::Tracing` | `lib/labkit/tracing/` | OpenTelemetry and legacy OpenTracing |
26
+ | `Labkit::Metrics` | `lib/labkit/metrics/` | Prometheus client wrappers |
27
+ | `Labkit::ApplicationSli`, `Labkit::UserExperienceSli` | `lib/labkit/application_sli/`, `lib/labkit/user_experience_sli/` | Apdex and error-rate SLIs |
28
+ | `Labkit::RateLimit` | `lib/labkit/rate_limit/` | Rules-based, Redis-backed rate limiting, see below |
29
+ | `Labkit::Middleware` | `lib/labkit/middleware/` | Rack and Sidekiq middleware for context, tracing, and SLIs |
30
+ | `Labkit::JsonSchema` | `lib/labkit/json_schema/` | `RefResolver` for remote `$ref` in JSON schemas. Not autoloaded; required by `UserExperienceSli` |
31
+ | `Labkit::FIPS` | `lib/labkit/fips.rb` | FIPS mode detection and OpenSSL digest substitution |
32
+ | `Labkit::System` | `lib/labkit/system.rb` | Monotonic clock helper used by metrics, tracing, and logging |
33
+ | `Labkit::Redis` | `lib/labkit/redis/` | Redis helpers shared by capabilities |
34
+ | `Labkit::Fields` | `lib/labkit/fields.rb` | Generated by labkit-spec CI from `schema/fields.yaml`. Change the field there, not here |
35
+ | `Labkit::RSpec` | `lib/labkit/rspec/` | Matchers for consumers' test suites. Not autoloaded; `require "labkit/rspec/matchers"` |
36
+
37
+ `lib/labkit/*_publisher.rb` hook Excon, HTTPClient, and Net::HTTP to publish outbound request notifications.
38
+
39
+ Modules with their own README (`lib/labkit/<module>/README.md`) document their public API there.
40
+ Update that README in the same MR as a behaviour change.
41
+
42
+ ## Commands
43
+
44
+ ```shell
45
+ bundle install
46
+ bundle exec rake verify # rspec + rubocop, what CI runs
47
+ bundle exec rake fix # rubocop autocorrect
48
+ bundle exec rspec spec/labkit/<module> # one module's specs
49
+ bundle exec rake console # IRB with the gem loaded
50
+ ```
51
+
52
+ Specs that need Redis use the instance at `LABKIT_TEST_REDIS_URL`, default `redis://localhost:6390/0`.
53
+ If nothing answers there and `LABKIT_TEST_REDIS_URL` is unset, the suite starts one with `docker compose up -d redis` and stops it at exit.
54
+ A Redis already listening on that URL is used as is and left running.
55
+ Autostart is off when `LABKIT_TEST_REDIS_URL` is set, even to the default value, when `CI` is set, or when `LABKIT_TEST_REDIS_NO_AUTOSTART=1` is set.
56
+ In those cases, start Redis yourself.
57
+
58
+ Style is `gitlab-styles` via RuboCop with `NewCops: enable`.
59
+ Do not edit `.rubocop_todo.yml` to silence a new offence; fix the code.
60
+ Tool versions come from `.tool-versions` through mise.
61
+
62
+ ## CI
63
+
64
+ - `rspec` runs the suite with a Redis service.
65
+ - `ruby-versions` and `legacy-ruby-versions` repeat it on Ruby 3.4 and 3.3. The versions are set in `.gitlab-ci.yml`, not read from the gemspec.
66
+ - `conformance-spec` triggers a downstream pipeline in labkit-spec that checks out this MR's commit and runs the conformance harness against it.
67
+ It runs when `lib/`, the gemspec, the Gemfile, or `.gitlab-ci.yml` change, and a red downstream run blocks the merge.
68
+ Renovate's bot user cannot start pipelines in labkit-spec, so on its MRs the job has `allow_failure: true` and a human rerun is the gate.
69
+ - Danger runs the shared `gitlab-dangerfiles` checks except changelog and commit message, which semantic-release owns.
70
+
71
+ ## Commits, MRs, and releases
72
+
73
+ Conventional Commits: `feat`, `fix`, `perf`, `revert`, `docs`, `refactor`, `test`, `chore`, `ci`, `style`.
74
+ Scope is the module, for example `fix(rate_limit): ...`.
75
+
76
+ Releases are cut from `master` and the `N-N-stable` branches by semantic-release with the `conventionalcommits` preset, so the commit type decides the version bump.
77
+
78
+ | Type | Release |
79
+ | --- | --- |
80
+ | `feat!`, or any type with a `BREAKING CHANGE:` footer | major |
81
+ | `feat` | minor |
82
+ | `fix`, `perf`, `revert` | patch |
83
+ | `docs`, `refactor`, `test`, `chore`, `ci`, `style` | none |
84
+
85
+ There is no hand-edited changelog.
86
+
87
+ Public APIs stay backward compatible.
88
+ Add keyword arguments with defaults; do not add required parameters or rename public methods.
89
+ Keep an MR to one concern, and separate mechanical changes such as renames from behavioural ones.
90
+
91
+ ## Rate limiting
92
+
93
+ `Labkit::RateLimit` is documented in `lib/labkit/rate_limit/README.md`.
94
+ It is the one capability that shares state across SDKs: services in any language enforce the same limits against the same Redis.
95
+ That makes the Redis key shape and the Lua scripts as much a contract as the HTTP headers, so changes here follow stricter rules than the rest of the gem.
96
+
97
+ ### Where each SDK keeps it
98
+
99
+ | SDK | Repository | Module | Tests | Status |
100
+ | --- | --- | --- | --- | --- |
101
+ | Ruby (this repository) | gitlab-org/ruby/gems/labkit-ruby | `lib/labkit/rate_limit/` | `spec/labkit/rate_limit/` | released |
102
+ | Go | gitlab-org/labkit | `v2/ratelimit/` | `v2/ratelimit/*_test.go`, run with `go -C v2 test ./ratelimit/...` | released |
103
+ | Rust | gitlab-org/rust/labkit-rs | in progress | | not released, skip |
104
+ | Python | gitlab-org/labkit-python | in progress | | not released, skip |
105
+ | Spec | gitlab-org/quality/tooling/labkit-spec | `conformance/README.md` ("v1 decisions"), `conformance/ratelimit_scenarios/*.json`, `conformance/aspect_ratelimit.go` | `conformance/` | judge |
106
+
107
+ ### The three layers
108
+
109
+ Every SDK must agree on three layers.
110
+ This section defines the layers; the current values (key grammar, header names, counting rules, metric names, log fields) live in labkit-spec, in the "v1 decisions" list in `conformance/README.md` and the scenarios under `conformance/ratelimit_scenarios/`.
111
+ If this file and labkit-spec disagree, labkit-spec wins.
112
+
113
+ 1. **Storage contract.**
114
+ Anything written to or read from Redis: key shape and prefix, how values are encoded, TTL rules, and the Lua scripts.
115
+ Two SDKs sharing one Redis with different storage rules keep two counters for one limit.
116
+ Never change this layer in one SDK.
117
+ It changes in labkit-spec first, then every SDK follows.
118
+ 2. **Observable contract.**
119
+ Anything a caller or an operator can see: response status and headers, the counting rule that decides a block, log line messages and field sets, metric families and labels.
120
+ Also changes in labkit-spec first.
121
+ 3. **Behaviour within the contract.**
122
+ Input validation and edge cases the contract already implies, where one SDK does something the contract does not allow.
123
+ These may be fixed SDK by SDK, and every SDK should end up the same.
124
+
125
+ A change that mixes layers is governed by the strictest one: storage, then observable, then behaviour.
126
+ When a change does not fit one layer clearly, say so in the MR instead of picking one.
127
+
128
+ ### Rules for rate-limit changes
129
+
130
+ - A change to layer 1 or 2 opens a labkit-spec MR first and waits for it to merge.
131
+ - A change to layer 3 should be checked against the Go SDK.
132
+ If Go has the same gap, say so in the MR so it can be ported.
133
+ - When a review finds a divergence between SDKs, a conformance scenario in labkit-spec must follow in the same week, so the harness sees the gap next time.
134
+ The author of the MR where the divergence was found owns this.
135
+ Mention the sync agent on the review thread to have it draft the scenario MR; if it cannot, open a labkit-spec issue and link it from the thread.
136
+ - Never edit Lua scripts, key construction, header names, metric names, or log field names to fix a Ruby-only bug.
137
+ If a fix seems to need that, it is a contract change.
138
+ =======
139
+ # Agent guidelines
140
+
141
+ This project uses [Conventional Commits](https://www.conventionalcommits.org/).
142
+ Commit messages drive automated [semantic releases](https://semantic-release.gitbook.io/)
143
+ (see `.releaserc.json`), so use `feat:`, `fix:`, etc. prefixes to ensure the
144
+ correct version bump and changelog entry.
145
+
146
+ ## AI-authored GitLab comments
147
+
148
+ Wrap the full body of any comment, note, or reply you post to GitLab (issues,
149
+ merge requests, epics — via `glab`/`glab api`) in `<:robot:>` / `</:robot:>`
150
+ tags (GitLab emoji shortcode, renders as 🤖), so readers can tell at a glance
151
+ that it's AI-generated:
152
+
153
+ ```
154
+ <:robot:>
155
+
156
+ ...full comment body...
157
+
158
+ </:robot:>
159
+ ```
160
+
161
+ This applies to newly posted comments. It does not apply to code, commit
162
+ messages, or MR/issue descriptions unless asked.
163
+
164
+ <!--
165
+ ####################################################################
166
+ # 🌊✨ PLEASE ADD PROJECT SPECIFIC RULES BELOW THIS LINE ✨🌊 #
167
+ # The section above is managed by the common-template-copier #
168
+ # template and is updated automatically on `copier update`. #
169
+ # Add your project-specific instructions below this line so #
170
+ # they are preserved when the template is updated. #
171
+ ####################################################################
172
+ -->
173
+ >>>>>>> after updating
data/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
data/CODEOWNERS CHANGED
@@ -1,4 +1,4 @@
1
1
  # CODEOWNERS is used to lookup assignees for
2
2
  # Renovate Bot dependency change Merge Requests.
3
3
  # https://docs.renovatebot.com/configuration-options/#assigneesfromcodeowners
4
- * @reprazent @andrewn @ayufan @hmerscher @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2
4
+ * @reprazent @ayufan @hmerscher @e_forbes @M_Alvarez @mwoolf @sankalp_gl @hardikgala @nindurkar @ashs2
data/Gemfile CHANGED
@@ -3,3 +3,8 @@
3
3
  source "https://rubygems.org"
4
4
 
5
5
  gemspec
6
+
7
+ # Exports RSpec results to the DX Observer when GLCI_OBSERVER_AUTH_TOKEN is set.
8
+ # Exporter source: https://gitlab.com/gitlab-org/quality/analytics/test-metrics-exporters
9
+ # Owned by: @gitlab-org/quality/analytics (group::development analytics)
10
+ gem 'gitlab-rspec-metrics-exporter', '~> 0.2', groups: [:development, :test]
data/README.md CHANGED
@@ -80,27 +80,14 @@ pass.
80
80
 
81
81
  Please also review the [development section of the LabKit (go) README](https://gitlab.com/gitlab-org/labkit#developing-labkit) for details of the LabKit architectural philosophy.
82
82
 
83
- To work on some of the scripts we use for releasing a new version,
84
- make sure to add a new `.env.sh`.
85
-
86
- ```console
87
- cp .env.example.sh .env.sh`
88
- ```
89
-
90
- Inside `.env.sh`, add a personal acccess token for the `CHANGELOG_GITLAB_TOKEN`
91
- environment variable. Next source the file:
92
-
93
- ```console
94
- . .env.sh
95
- ```
96
-
97
83
  ### Releasing a new version
98
84
 
99
- Releasing a new version can be done by pushing a new tag, or creating
100
- it from the
101
- [interface](https://gitlab.com/gitlab-org/labkit-ruby/-/tags).
102
-
103
- A new changelog will automatically be added to the release on Gitlab.
85
+ Releases are cut automatically by
86
+ [semantic-release](https://github.com/semantic-release/semantic-release)
87
+ when changes are merged to `master` or to an `N-N-stable` branch. The
88
+ [Conventional Commits](https://www.conventionalcommits.org/) type of each
89
+ commit decides the version bump (see [AGENTS.md](AGENTS.md)), and the
90
+ release notes are generated from those commit messages.
104
91
 
105
92
  The new version will automatically be published to `gitlab-labkit` on
106
93
  [rubygems](https://rubygems.org/gems/gitlab-labkit) when the pipeline
@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
36
36
  spec.add_runtime_dependency "pg_query", ">= 6.1.0", "< 7.0"
37
37
  spec.add_runtime_dependency "prometheus-client-mmap", ">= 1.2", "< 2.0"
38
38
  spec.add_runtime_dependency "redis", "> 3.0.0", "< 6.0.0"
39
+ spec.add_runtime_dependency "thrift", "< 0.25" # Pinned for jaeger-client 1.1.0 compatibility; thrift 0.25 requires transports to implement message_boundaries?
39
40
 
40
41
  # Please maintain alphabetical order for dev dependencies
41
42
  spec.add_development_dependency "excon", "~> 0.78.1"
data/lib/labkit/fields.rb CHANGED
@@ -138,6 +138,17 @@ module Labkit
138
138
  # (e.g. newlines) to prevent log injection.
139
139
  ADDITIONAL_DETAILS = "additional_details"
140
140
 
141
+ # Unrounded complexity score of a GraphQL query. Some fields have a
142
+ # fractional cost (e.g. graphql-ruby's __typename costs 0.2), so the total
143
+ # can be a non-integer value.
144
+ GRAPHQL_COMPLEXITY_RAW = "graphql_complexity_raw"
145
+
146
+ # Number of nodes a GraphQL query returned across all its connection fields.
147
+ # The count is taken after authorization removes the nodes the user can't
148
+ # see. Nested connections add up. The value is 0 when the query selects no
149
+ # connection field.
150
+ GRAPHQL_CONNECTION_NODES = "graphql_connection_nodes"
151
+
141
152
  # Maps each field constant to its logging field variant version.
142
153
  # A version of 0 means the field is not yet assigned to any variant.
143
154
  VARIANT_VERSION = {
@@ -179,6 +190,8 @@ module Labkit
179
190
  ROOT_CALLER_ID => 0,
180
191
  GL_SENT_NOTIFICATION_ID => 0,
181
192
  ADDITIONAL_DETAILS => 0,
193
+ GRAPHQL_COMPLEXITY_RAW => 0,
194
+ GRAPHQL_CONNECTION_NODES => 0,
182
195
  }.freeze
183
196
 
184
197
  # Get the constant name for a field value
@@ -207,8 +220,8 @@ module Labkit
207
220
  Fields::DURATION_S => %w[duration duration_ms elapsed_time actual_duration time_ms total_time gitaly.duration],
208
221
  Fields::REMOTE_IP => %w[ip source_ip ip_address],
209
222
  Fields::HTTP_HOST => %w[hostname request_host gitlab_host kubernetes.host],
210
- Fields::GL_PROJECT_ID => %w[extra.project_id meta.project_id meta.search.project_id job_project_id target_project_id],
211
- Fields::GL_PIPELINE_ID => %w[extra.pipeline_id meta.pipeline_id root_pipeline_id],
223
+ Fields::GL_PROJECT_ID => %w[project_id extra.project_id meta.project_id meta.search.project_id job_project_id target_project_id],
224
+ Fields::GL_PIPELINE_ID => %w[pipeline_id extra.pipeline_id meta.pipeline_id root_pipeline_id],
212
225
  Fields::TIMESTAMP => %w[start_time],
213
226
  Fields::SEVERITY => %w[level],
214
227
  Fields::LOG_MESSAGE => %w[msg custom_message extra.message fields.message graphql.message reason color_message exception.gitaly],
@@ -66,7 +66,7 @@ Labkit::JsonSchema::RefResolver.cache.clear
66
66
 
67
67
  ## Use Case Example
68
68
 
69
- The `RefResolver` is used in the User Experience SLI Registry [lib/labkit/user_experience_sli/registry.rb](lib/labkit/user_experience_sli/registry.rb) to validate user experience definitions against a JSON schema.
69
+ The `RefResolver` is used in the User Experience SLI Registry [lib/labkit/user_experience_sli/registry.rb](../user_experience_sli/registry.rb) to validate user experience definitions against a JSON schema.
70
70
 
71
71
  ## Implementation Details
72
72