gitlab-labkit 5.3.0 → 5.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e333c26dffb8c22bb8a131e820b01920887c2792dcffcee8f4ee012663b70831
-  data.tar.gz: 1cd8ac6e3b87b8bf1e214234e0d44dfc2b593798554fb1a1206d6e94cc8a2863
+  metadata.gz: aed1a8c61c569399190d8729a7121c1f45a5d4cd9d95f0f94cb83712f369d4c5
+  data.tar.gz: 7c20c5fe22b0012fd0149d238b525254d18a97da8df75e2bdf7c83da5f25796f
 SHA512:
-  metadata.gz: 4f602e792b4e8573f1ce8e29a9654221f274a3789e262af412f3b52a937970f5605748bbf9f4580698f6457436c561c905c7e1021e964f545bc511508892f8bc
-  data.tar.gz: b131bf8715cecbd30484b89299607b9781e6cda5c690da7dc24f851b1558fdd5eb78a417cbd9baaaf2d93393d3694de8c98aa180b0103e27f5e61d598aa110a8
+  metadata.gz: 33023dcf68427b86e1c63440e7edc0795a1cd612dea306e025170ad3a070cd394622e69d2b9f8b44dcae63674a3f70bf4715b5e2c0e1dd19cb5fdc884a0c7137
+  data.tar.gz: dd800774b482b0b51c79640d1b97080ce5688fb30e2c06b6b0542606a1e7b08ec719a17c4b0111cc39f697c9582bc4abe790a8f94f94942cdfd5d0e630dc410c

data/AGENTS.md

@@ -0,0 +1,136 @@
+# AGENTS.md
+
+Instructions for AI agents and automated tooling working in this repository.
+
+## Project context
+
+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.
+It is consumed by GitLab Rails and other Ruby services, so every public API is a compatibility commitment.
+
+It is one of several LabKit SDKs.
+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)).
+Behaviour that services observe, and anything written to a shared store, must be the same in every SDK.
+The contract lives in [labkit-spec](https://gitlab.com/gitlab-org/quality/tooling/labkit-spec), and its conformance harness is the judge.
+
+### Layout
+
+One gem, one `Labkit` namespace, one directory per capability under `lib/labkit/`.
+`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.
+
+| Module | Directory | Notes |
+| --- | --- | --- |
+| `Labkit::Context`, `Labkit::Correlation` | `lib/labkit/context.rb`, `lib/labkit/correlation/` | Request context for logs and propagation |
+| `Labkit::Logging` | `lib/labkit/logging/` | Log sanitisation and JSON formatting |
+| `Labkit::Tracing` | `lib/labkit/tracing/` | OpenTelemetry and legacy OpenTracing |
+| `Labkit::Metrics` | `lib/labkit/metrics/` | Prometheus client wrappers |
+| `Labkit::ApplicationSli`, `Labkit::UserExperienceSli` | `lib/labkit/application_sli/`, `lib/labkit/user_experience_sli/` | Apdex and error-rate SLIs |
+| `Labkit::RateLimit` | `lib/labkit/rate_limit/` | Rules-based, Redis-backed rate limiting, see below |
+| `Labkit::Middleware` | `lib/labkit/middleware/` | Rack and Sidekiq middleware for context, tracing, and SLIs |
+| `Labkit::JsonSchema` | `lib/labkit/json_schema/` | `RefResolver` for remote `$ref` in JSON schemas. Not autoloaded; required by `UserExperienceSli` |
+| `Labkit::FIPS` | `lib/labkit/fips.rb` | FIPS mode detection and OpenSSL digest substitution |
+| `Labkit::System` | `lib/labkit/system.rb` | Monotonic clock helper used by metrics, tracing, and logging |
+| `Labkit::Redis` | `lib/labkit/redis/` | Redis helpers shared by capabilities |
+| `Labkit::Fields` | `lib/labkit/fields.rb` | Generated by labkit-spec CI from `schema/fields.yaml`. Change the field there, not here |
+| `Labkit::RSpec` | `lib/labkit/rspec/` | Matchers for consumers' test suites. Not autoloaded; `require "labkit/rspec/matchers"` |
+
+`lib/labkit/*_publisher.rb` hook Excon, HTTPClient, and Net::HTTP to publish outbound request notifications.
+
+Modules with their own README (`lib/labkit/<module>/README.md`) document their public API there.
+Update that README in the same MR as a behaviour change.
+
+## Commands
+
+```shell
+bundle install
+bundle exec rake verify                        # rspec + rubocop, what CI runs
+bundle exec rake fix                           # rubocop autocorrect
+bundle exec rspec spec/labkit/<module>         # one module's specs
+bundle exec rake console                       # IRB with the gem loaded
+```
+
+Specs that need Redis use the instance at `LABKIT_TEST_REDIS_URL`, default `redis://localhost:6390/0`.
+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.
+A Redis already listening on that URL is used as is and left running.
+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.
+In those cases, start Redis yourself.
+
+Style is `gitlab-styles` via RuboCop with `NewCops: enable`.
+Do not edit `.rubocop_todo.yml` to silence a new offence; fix the code.
+Tool versions come from `.tool-versions` through mise.
+
+## CI
+
+- `rspec` runs the suite with a Redis service.
+- `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.
+- `conformance-spec` triggers a downstream pipeline in labkit-spec that checks out this MR's commit and runs the conformance harness against it.
+  It runs when `lib/`, the gemspec, the Gemfile, or `.gitlab-ci.yml` change, and a red downstream run blocks the merge.
+  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.
+- Danger runs the shared `gitlab-dangerfiles` checks except changelog and commit message, which semantic-release owns.
+
+## Commits, MRs, and releases
+
+Conventional Commits: `feat`, `fix`, `perf`, `revert`, `docs`, `refactor`, `test`, `chore`, `ci`, `style`.
+Scope is the module, for example `fix(rate_limit): ...`.
+
+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.
+
+| Type | Release |
+| --- | --- |
+| `feat!`, or any type with a `BREAKING CHANGE:` footer | major |
+| `feat` | minor |
+| `fix`, `perf`, `revert` | patch |
+| `docs`, `refactor`, `test`, `chore`, `ci`, `style` | none |
+
+There is no hand-edited changelog.
+
+Public APIs stay backward compatible.
+Add keyword arguments with defaults; do not add required parameters or rename public methods.
+Keep an MR to one concern, and separate mechanical changes such as renames from behavioural ones.
+
+## Rate limiting
+
+`Labkit::RateLimit` is documented in `lib/labkit/rate_limit/README.md`.
+It is the one capability that shares state across SDKs: services in any language enforce the same limits against the same Redis.
+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.
+
+### Where each SDK keeps it
+
+| SDK | Repository | Module | Tests | Status |
+| --- | --- | --- | --- | --- |
+| Ruby (this repository) | gitlab-org/ruby/gems/labkit-ruby | `lib/labkit/rate_limit/` | `spec/labkit/rate_limit/` | released |
+| Go | gitlab-org/labkit | `v2/ratelimit/` | `v2/ratelimit/*_test.go`, run with `go -C v2 test ./ratelimit/...` | released |
+| Rust | gitlab-org/rust/labkit-rs | in progress | | not released, skip |
+| Python | gitlab-org/labkit-python | in progress | | not released, skip |
+| Spec | gitlab-org/quality/tooling/labkit-spec | `conformance/README.md` ("v1 decisions"), `conformance/ratelimit_scenarios/*.json`, `conformance/aspect_ratelimit.go` | `conformance/` | judge |
+
+### The three layers
+
+Every SDK must agree on three layers.
+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/`.
+If this file and labkit-spec disagree, labkit-spec wins.
+
+1. **Storage contract.**
+   Anything written to or read from Redis: key shape and prefix, how values are encoded, TTL rules, and the Lua scripts.
+   Two SDKs sharing one Redis with different storage rules keep two counters for one limit.
+   Never change this layer in one SDK.
+   It changes in labkit-spec first, then every SDK follows.
+2. **Observable contract.**
+   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.
+   Also changes in labkit-spec first.
+3. **Behaviour within the contract.**
+   Input validation and edge cases the contract already implies, where one SDK does something the contract does not allow.
+   These may be fixed SDK by SDK, and every SDK should end up the same.
+
+A change that mixes layers is governed by the strictest one: storage, then observable, then behaviour.
+When a change does not fit one layer clearly, say so in the MR instead of picking one.
+
+### Rules for rate-limit changes
+
+- A change to layer 1 or 2 opens a labkit-spec MR first and waits for it to merge.
+- A change to layer 3 should be checked against the Go SDK.
+  If Go has the same gap, say so in the MR so it can be ported.
+- 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.
+  The author of the MR where the divergence was found owns this.
+  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.
+- Never edit Lua scripts, key construction, header names, metric names, or log field names to fix a Ruby-only bug.
+  If a fix seems to need that, it is a contract change.

data/gitlab-labkit.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "pg_query", ">= 6.1.0", "< 7.0"
   spec.add_runtime_dependency "prometheus-client-mmap", ">= 1.2", "< 2.0"
   spec.add_runtime_dependency "redis", "> 3.0.0", "< 6.0.0"
+  spec.add_runtime_dependency "thrift", "< 0.25" # Pinned for jaeger-client 1.1.0 compatibility; thrift 0.25 requires transports to implement message_boundaries?
 
   # Please maintain alphabetical order for dev dependencies
   spec.add_development_dependency "excon", "~> 0.78.1"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 5.3.0
+  version: 5.3.1
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -277,6 +277,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: thrift
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.25'
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
@@ -568,6 +582,7 @@ files:
 - ".rufo"
 - ".tool-versions"
 - ".yamllint.yaml"
+- AGENTS.md
 - CODEOWNERS
 - CONTRIBUTING.md
 - Dangerfile