jamm 2.4.0 → 2.5.0

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: 17f04171e0380f881d022d968eafaecfab7de2ca6e0a91ed56b217a4434afcab
4
- data.tar.gz: 2f98a4766f79146afc5a839a26b2f69674ac87330065f663d9c90441a52b5f74
3
+ metadata.gz: fe888992acfb9739e5206ab7aaa3428f3e246998e633ff60e09999c2d96f3992
4
+ data.tar.gz: 6ee9932e4775b93a8b18e9dba2173871d6c36b0e727563111c8462801db481e3
5
5
  SHA512:
6
- metadata.gz: 1182b1fc82f6d8c009e9f98542baf35e2b4542ff81f8b49ba4de35319662a8a2bcec5e47f35b2f45041a491f4d9c7697997259263426960d11493cefa0eef547
7
- data.tar.gz: a17d3a2f3a352b39a8c2021593dc24e4d960afd460bc2ecdea038186b078e9df92d8b6e6b0e9965995cf50408c1327eef01dbd3ffd39909aa222636e8155b337
6
+ metadata.gz: c33699a5edbb8cd8f52c5848bc5534b735f9ebca0990b45ceb2105408a2e5fbad7aca6205a0f788c5b6213e954d9a9c56e7d7f71f8f2cb47f491f7786afe658d
7
+ data.tar.gz: 73722cb39c3acbbd828c8011e4303f0ff1a8936b1dd390f34edbef5fe9dc26cf3375d6f025a8b20c8abd3e2a37fe80e3fbdc97b195dbbd899fcde93a099c3260
data/CHANGELOG.md CHANGED
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.5.0] - 2026-07-03
9
+
10
+ ### Added
11
+
12
+ - Added `Jamm::Webhook.verify_and_parse(raw_body)` — verifies the HMAC signature over the exact received `content` bytes and parses in one step. Unlike `Jamm::Webhook.verify`, it is not broken by JSON re-serialization (correctly handles `&`, `<`, `>` in content) and rejects bodies with duplicate top-level keys.
13
+
8
14
  ## [2.4.0] - 2026-07-01
9
15
 
10
16
  ### Added
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- jamm (2.4.0)
4
+ jamm (2.5.0)
5
5
  base64 (~> 0.2)
6
6
  rest-client (~> 2.0)
7
7
  typhoeus (~> 1.0, >= 1.0.1)
data/jamm.gemspec CHANGED
@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
21
21
 
22
22
  s.files = `git ls-files`.split("\n").reject do |file|
23
23
  file.start_with?(
24
+ 'compatibility',
24
25
  'examples',
25
26
  'images',
26
27
  'openapi',
data/lib/jamm/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Jamm
4
- VERSION = '2.4.0'
4
+ VERSION = '2.5.0'
5
5
  end
data/lib/jamm/webhook.rb CHANGED
@@ -63,6 +63,118 @@ module Jamm
63
63
  raise Jamm::InvalidSignatureError, 'Digests do not match'
64
64
  end
65
65
 
66
+ # Verify the HMAC signature over the exact received bytes and parse, in one step.
67
+ #
68
+ # This is the recommended entry point. The backend signs the raw +content+ bytes it
69
+ # transmits, produced by Go's JSON encoder which HTML-escapes & < > as & <
70
+ # >. Re-serializing the parsed content (as +verify+ does via JSON.dump) un-escapes
71
+ # those characters, so its digest no longer matches. This slices the raw +content+
72
+ # substring out of +raw_body+ verbatim and HMACs that.
73
+ def self.verify_and_parse(raw_body)
74
+ raise ArgumentError, 'raw_body cannot be nil or empty' if raw_body.nil? || raw_body.empty?
75
+
76
+ parsed = JSON.parse(raw_body, symbolize_names: true)
77
+ signature = parsed[:signature]
78
+ raise ArgumentError, "Webhook body is missing the 'signature' field" if signature.nil? || signature.empty?
79
+
80
+ raw_content = extract_raw_content(raw_body)
81
+ digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), Jamm.client_secret, raw_content)
82
+ given = "sha256=#{digest}"
83
+ raise Jamm::InvalidSignatureError, 'Digests do not match' unless secure_compare(given, signature)
84
+
85
+ parse(parsed)
86
+ end
87
+
88
+ # Extracts the top-level +content+ value substring from a raw webhook body verbatim,
89
+ # without decoding or re-serializing it, so the exact signed bytes are recovered.
90
+ def self.extract_raw_content(raw_body)
91
+ i = 0
92
+ n = raw_body.length
93
+ i += 1 while i < n && raw_body[i].match?(/\s/)
94
+ raise ArgumentError, 'Webhook body must be a JSON object' unless raw_body[i] == '{'
95
+
96
+ i += 1
97
+ # Scan every top-level key. Duplicate keys are rejected: JSON.parse keeps the LAST
98
+ # occurrence while this returns the FIRST, so a duplicate `content` could otherwise
99
+ # verify one payload and parse another (signature bypass).
100
+ seen = {}
101
+ content = nil
102
+ loop do
103
+ i += 1 while i < n && (raw_body[i].match?(/\s/) || raw_body[i] == ',')
104
+ break if i >= n || raw_body[i] == '}'
105
+ raise ArgumentError, 'Malformed webhook JSON' unless raw_body[i] == '"'
106
+
107
+ key_start = i
108
+ i = skip_string(raw_body, i)
109
+ # Decode the key (not a raw slice): otherwise an escaped duplicate such as
110
+ # "content" would evade both the duplicate check and the 'content' match below,
111
+ # while JSON.parse collapses it to `content` and keeps the last value. Normalize a
112
+ # malformed key to ArgumentError to match the rest of this method.
113
+ key = begin
114
+ JSON.parse(raw_body[key_start...i])
115
+ rescue JSON::ParserError
116
+ raise ArgumentError, 'Malformed webhook JSON'
117
+ end
118
+ raise ArgumentError, "Duplicate top-level key in webhook body: #{key}" if seen.key?(key)
119
+
120
+ seen[key] = true
121
+ i += 1 while i < n && raw_body[i].match?(/\s/)
122
+ raise ArgumentError, 'Malformed webhook JSON' unless raw_body[i] == ':'
123
+
124
+ i += 1
125
+ i += 1 while i < n && raw_body[i].match?(/\s/)
126
+ value_start = i
127
+ i = skip_value(raw_body, i)
128
+ content = raw_body[value_start...i] if key == 'content'
129
+ end
130
+ raise ArgumentError, "Webhook body does not contain 'content' field" if content.nil?
131
+
132
+ content
133
+ end
134
+
135
+ # +i+ points at an opening '"'. Returns the index just past the closing '"'.
136
+ def self.skip_string(str, i)
137
+ i += 1
138
+ n = str.length
139
+ while i < n
140
+ c = str[i]
141
+ if c == '\\'
142
+ i += 2
143
+ next
144
+ end
145
+ return i + 1 if c == '"'
146
+
147
+ i += 1
148
+ end
149
+ raise ArgumentError, 'Unterminated string in webhook JSON'
150
+ end
151
+
152
+ # +i+ points at the first char of a JSON value. Returns the index just past it.
153
+ def self.skip_value(str, i)
154
+ return skip_string(str, i) if str[i] == '"'
155
+
156
+ if str[i] == '{' || str[i] == '['
157
+ depth = 0
158
+ n = str.length
159
+ while i < n
160
+ ch = str[i]
161
+ if ch == '"'
162
+ i = skip_string(str, i)
163
+ next
164
+ elsif ch == '{' || ch == '['
165
+ depth += 1
166
+ elsif ch == '}' || ch == ']'
167
+ depth -= 1
168
+ return i + 1 if depth.zero?
169
+ end
170
+ i += 1
171
+ end
172
+ raise ArgumentError, 'Unterminated object/array in webhook JSON'
173
+ end
174
+ i += 1 while i < str.length && !",}] \t\n\r".include?(str[i])
175
+ i
176
+ end
177
+
66
178
  # Securely compare two strings of equal length.
67
179
  # This method is a port of ActiveSupport::SecurityUtils.secure_compare
68
180
  # which works on non-Rails platforms.
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: jamm
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.4.0
4
+ version: 2.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jamm
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-07-01 00:00:00.000000000 Z
11
+ date: 2026-07-15 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: base64
@@ -72,32 +72,6 @@ files:
72
72
  - LICENSE
73
73
  - README.md
74
74
  - Rakefile
75
- - compatibility/.gitignore
76
- - compatibility/1.3.0/Gemfile
77
- - compatibility/1.3.0/compat_test.rb
78
- - compatibility/1.4.0/Gemfile
79
- - compatibility/1.4.0/compat_test.rb
80
- - compatibility/1.4.1/Gemfile
81
- - compatibility/1.4.1/compat_test.rb
82
- - compatibility/1.5.0/Gemfile
83
- - compatibility/1.5.0/compat_test.rb
84
- - compatibility/1.6.0/Gemfile
85
- - compatibility/1.6.0/compat_test.rb
86
- - compatibility/1.7.0/Gemfile
87
- - compatibility/1.7.0/compat_test.rb
88
- - compatibility/2.0.0/Gemfile
89
- - compatibility/2.0.0/compat_test.rb
90
- - compatibility/2.1.0/Gemfile
91
- - compatibility/2.1.0/compat_test.rb
92
- - compatibility/2.2.0/Gemfile
93
- - compatibility/2.2.0/compat_test.rb
94
- - compatibility/2.3.0/Gemfile
95
- - compatibility/2.3.0/compat_test.rb
96
- - compatibility/Makefile
97
- - compatibility/README.md
98
- - compatibility/shared/suite.rb
99
- - compatibility/templates/Gemfile.tmpl
100
- - compatibility/templates/compat_test.rb.tmpl
101
75
  - jamm.gemspec
102
76
  - lib/jamm.rb
103
77
  - lib/jamm/api.rb
@@ -1,11 +0,0 @@
1
- # Per-version status emitted by `make report` for the PR comment workflow.
2
- compat-report.tsv
3
-
4
- # Installed published gems and per-directory bundler state -- pulled fresh from
5
- # the registry per run.
6
- */.bundle
7
- */vendor
8
-
9
- # Lockfiles are intentionally untracked: these install real published versions
10
- # from the registry and are out of scope for our vulnerability checks.
11
- */Gemfile.lock
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.3.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '1.3.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.3.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@1.3.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '1.3.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.4.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '1.4.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.4.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@1.4.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '1.4.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.4.1` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '1.4.1'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.4.1` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@1.4.1 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '1.4.1'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.5.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '1.5.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.5.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@1.5.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '1.5.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.6.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '1.6.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.6.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@1.6.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '1.6.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.7.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '1.7.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=1.7.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@1.7.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '1.7.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.0.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '2.0.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.0.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@2.0.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '2.0.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.1.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '2.1.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.1.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@2.1.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '2.1.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.2.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '2.2.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.2.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@2.2.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '2.2.0'
16
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.3.0` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '2.3.0'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=2.3.0` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@2.3.0 (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '2.3.0'
16
- end
@@ -1,63 +0,0 @@
1
- .PHONY: ls install test report clean add
2
-
3
- WORKDIR := /services/packages/sdk/ruby/compatibility
4
-
5
- # Run inside the api container (same pattern as the parent SDK Makefile) so the
6
- # SDK's env: 'local' host (api.jamm.test) resolves to the local backend.
7
- ifneq ($(WORKDIR), $(PWD))
8
- EXEC := docker compose exec -w $(WORKDIR) api
9
- endif
10
-
11
- # Pinned version directories -- everything except shared/ and templates/.
12
- VERSIONS := $(filter-out shared/ templates/,$(wildcard */))
13
-
14
- # List the version directories under test.
15
- ls:
16
- @echo "Compat versions:" $(VERSIONS:/=)
17
-
18
- # Install each pinned gem version into its own bundle (lockfiles are gitignored
19
- # on purpose). BUNDLE_GEMFILE scopes bundler to that directory's Gemfile.
20
- install:
21
- @$(EXEC) bash -c 'set -e; for d in $(VERSIONS); do \
22
- echo "== install $$d =="; \
23
- ( cd $$d && BUNDLE_GEMFILE=Gemfile bundle install ); \
24
- done'
25
-
26
- # Run the shared suite against every pinned version. Runs all versions even if
27
- # one fails, then exits non-zero if any did -- so a single broken version is
28
- # visible without masking the rest.
29
- test:
30
- @$(EXEC) bash -c 'rc=0; for d in $(VERSIONS); do \
31
- echo "== test $$d =="; \
32
- ( cd $$d && \
33
- MERCHANT_CLIENT_ID=$(MERCHANT_CLIENT_ID) \
34
- MERCHANT_CLIENT_SECRET=$(MERCHANT_CLIENT_SECRET) \
35
- BUNDLE_GEMFILE=Gemfile bundle exec ruby compat_test.rb ) || rc=1; \
36
- done; exit $$rc'
37
-
38
- # CI variant of `test`: runs every version, writes per-version status to
39
- # compat-report.tsv ("<version>\t<PASS|FAIL>"), and always exits 0. The
40
- # workflow turns the file into a PR comment, so the merge is not blocked when
41
- # an older published version is out of sync with the current API.
42
- report:
43
- @$(EXEC) bash -c 'rm -f compat-report.tsv; for d in $(VERSIONS); do \
44
- v=$${d%/}; \
45
- echo "== test $$v =="; \
46
- if ( cd $$d && \
47
- MERCHANT_CLIENT_ID=$(MERCHANT_CLIENT_ID) \
48
- MERCHANT_CLIENT_SECRET=$(MERCHANT_CLIENT_SECRET) \
49
- BUNDLE_GEMFILE=Gemfile bundle exec ruby compat_test.rb ); then status=PASS; else status=FAIL; fi; \
50
- printf "%s\t%s\n" "$$v" "$$status" >> compat-report.tsv; \
51
- done; echo "== summary =="; cat compat-report.tsv'
52
-
53
- # Remove installed bundles and lockfiles for every version.
54
- clean:
55
- @for d in $(VERSIONS); do rm -rf $$d/.bundle $$d/vendor $$d/Gemfile.lock; done
56
-
57
- # Scaffold a new version directory from the templates: make add VER=2.4.0
58
- add:
59
- @test -n "$(VER)" || { echo "usage: make add VER=x.y.z"; exit 1; }
60
- @mkdir -p "$(VER)"
61
- @sed 's/__VERSION__/$(VER)/g' templates/Gemfile.tmpl > "$(VER)/Gemfile"
62
- @sed 's/__VERSION__/$(VER)/g' templates/compat_test.rb.tmpl > "$(VER)/compat_test.rb"
63
- @echo "Created $(VER)/ -- run 'make install' then 'make test'."
@@ -1,119 +0,0 @@
1
- # Ruby SDK backward-compatibility tests
2
-
3
- This directory verifies that previously **published** versions of the `jamm` gem
4
- still work against the current API — i.e. that the SDKs and the backend stay in
5
- sync. The pre-release/latest SDK lives in `../lib` and is covered by
6
- `../test.e2e`; this directory covers the **released** versions pulled from the
7
- RubyGems registry.
8
-
9
- ## Layout
10
-
11
- ```
12
- packages/sdk/
13
- compatibility/
14
- testdata/ # language-neutral backend webhook records; shared by every SDK harness
15
- ruby/compatibility/
16
- shared/
17
- suite.rb # the shared, capability-gated smoke suite (single source of truth)
18
- templates/ # source templates for each version directory
19
- <version>/
20
- Gemfile # pins jamm@<version> + test-unit
21
- compat_test.rb # thin shim: requires the pinned gem, runs the shared suite
22
- Makefile
23
- ```
24
-
25
- Each `<version>/` directory installs its own pinned gem into its own bundle, so
26
- its `compat_test.rb` requires `jamm` and bundler resolves it to that directory's
27
- version. The shim then mixes `JammCompat::Tests` into a `Test::Unit::TestCase`,
28
- so the **same** assertions run against every version.
29
-
30
- Lockfiles (`Gemfile.lock`) and installed bundles are git-ignored on purpose:
31
- these install real published versions from the registry and are out of scope for
32
- our vulnerability checks.
33
-
34
- ## What is tested
35
-
36
- The suite is capability-gated, because the public surface grew over time. Where a
37
- service is missing in an older gem, its check is omitted (skipped) rather than
38
- failed:
39
-
40
- | Check | Touches API | Notes |
41
- | ------------------------------ | ----------- | ------------------------------------------------- |
42
- | `Jamm.configure` + environment | no | environment round-trips to `local` |
43
- | `Jamm::Healthcheck.ping` | yes | skipped unless `MERCHANT_CLIENT_*` are set |
44
- | `Jamm::Webhook.verify` | no | recomputes the HMAC signature; asserts the contract |
45
- | `Jamm::Webhook.parse` | no | forward-compat: parses backend records carrying newer fields (see below) |
46
-
47
- ### Forward-compatibility: `Jamm::Webhook.parse` against current-day records
48
-
49
- `../../compatibility/testdata/*.json` are webhook payloads shaped as the backend
50
- sends them, covering both shapes the harness cares about:
51
-
52
- - `charge_success_api_source.json` — a flat charge carrying `api_source`
53
- (`ChargeMessage` field 23). The backend marshals webhook content with Go's
54
- `json.Marshal` (not `protojson`), so the enum goes out as its numeric value
55
- (`"api_source": 3`); there is no enum-string form on the wire.
56
- - `refund_succeeded_nested_api_source.json` — the nested refund wrapper
57
- (`content.transaction` + `content.refund`) **with** `api_source`.
58
- - `refund_succeeded_nested_no_api_source.json` — the same nested wrapper
59
- **without** `api_source` (older backends, or charges created outside the charge
60
- API), which must also parse, resolving to the model's default.
61
-
62
- The suite asserts every parse-capable version **must** decode the core
63
- `ChargeMessage` (`id`, `customer`) and ignore fields it predates. A version that
64
- *has* `parse` but throws on these records **fails** the test — that failure is the
65
- signal it is out of sync with the API, not an accepted outcome (mirrors the Node
66
- harness).
67
-
68
- > [!IMPORTANT]
69
- > The `api_source` / nested-refund webhook feature was **rolled back on `main`**
70
- > for release (PR #2316, reverting #2304/#2281/#2282/…). As of that revert the
71
- > backend does **not** emit `api_source` in charge webhooks and the latest SDK
72
- > source (`../lib`, currently `2.2.0`) has no forward-compat parse. These fixtures
73
- > are retained deliberately — covering both the with- and without-`api_source`
74
- > shapes — so this harness is the ready-made signal for which published versions
75
- > tolerate the contract once it re-lands.
76
-
77
- Expected behavior across the pinned versions, from each gem's CHANGELOG (the
78
- authoritative matrix is whatever `make test` reports against the installed gems):
79
-
80
- | version | nested refund wrapper | `api_source` resolution | expected parse result |
81
- | -------------- | --------------------- | ----------------------- | ------------------------------------------------------ |
82
- | 1.3.0 – 1.7.0 | no | no | refund events unhandled → `parse` raises (out of sync) |
83
- | 2.0.0 – 2.2.0 | partial | no | strict decode throws on `api_source` (out of sync) |
84
- | 2.3.0 | yes | yes | ✅ decodes core fields, ignores/resolves newer fields |
85
-
86
- Verified locally: the suite passes 100% against a forward-compat-capable SDK
87
- source and fails the three `parse` fixtures against the reverted `2.2.0` source —
88
- i.e. the harness flags out-of-sync versions exactly as intended.
89
-
90
- ## Running
91
-
92
- Pinned versions are installed from the registry; the live `healthcheck` check
93
- talks to the local backend (`api.jamm.test`), so the suite runs inside the `api`
94
- container like the parent SDK's e2e tests.
95
-
96
- ```sh
97
- # from packages/sdk/ruby/compatibility
98
- make install # install all pinned versions
99
- make test \
100
- MERCHANT_CLIENT_ID=... \
101
- MERCHANT_CLIENT_SECRET=... # run the suite against every version
102
- ```
103
-
104
- Without credentials the offline checks still run and the live `healthcheck`
105
- check is skipped.
106
-
107
- ## Pinned versions
108
-
109
- The latest 10 versions published to the RubyGems registry (the installable
110
- source of truth): `1.3.0, 1.4.0, 1.4.1, 1.5.0, 1.6.0, 1.7.0, 2.0.0, 2.1.0,
111
- 2.2.0, 2.3.0`. The registry and the GitHub tags can disagree — pin to what
112
- RubyGems actually serves, since that is what merchants install.
113
-
114
- To add a newly released version:
115
-
116
- ```sh
117
- make add VER=2.4.0 # scaffolds 2.4.0/ from templates/
118
- make install && make test
119
- ```
@@ -1,146 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'json'
4
- require 'openssl'
5
- require 'test/unit'
6
-
7
- # Shared backward-compatibility smoke suite for the published `jamm` gem.
8
- #
9
- # Each compatibility/<version>/ directory pins and installs its own published gem
10
- # version (via its sibling Gemfile), then its compat_test.rb shim builds a
11
- # Test::Unit::TestCase that `include`s JammCompat::Tests. Pinning happens through
12
- # bundler, so `require 'jamm'` in that process resolves to *this* directory's
13
- # version and the same assertions run against every version.
14
- #
15
- # The suite is capability-gated: the public surface grew across versions, so a
16
- # check for a service that did not exist yet is omitted (skipped) rather than
17
- # failed. The one deliberate exception is webhook.parse -- see PARSE_FIXTURES.
18
- module JammCompat
19
- # Shared decoded-core assertions: every parse-capable version must decode these
20
- # from each fixture regardless of the newer fields it carries.
21
- EXPECTED = { id: 'trx-00000000000000000000', customer: 'cus-00000000000000000000' }.freeze
22
-
23
- # Backend webhook records shaped exactly as the current API emits them (see
24
- # packages/sdk/compatibility/testdata/), carrying fields newer than most published gems: api_source
25
- # (ChargeMessage field 23) and the nested { transaction, refund } refund
26
- # wrapper. The backend marshals webhook content with Go's json.Marshal (not
27
- # protojson), so enums go out numeric ("api_source": 3) -- there is no
28
- # enum-string form on the wire, so one fixture per record shape is enough.
29
- # Each charge/refund shape is covered both with and without api_source so the
30
- # post-revert backend (no api_source emitted) is exercised alongside the
31
- # re-landed-feature shape.
32
- PARSE_FIXTURES = [
33
- { file: 'charge_success_api_source.json', event: 'CHARGE_SUCCESS + api_source' },
34
- { file: 'charge_success_without_api_source.json', event: 'CHARGE_SUCCESS, no api_source' },
35
- { file: 'refund_succeeded_nested_api_source.json', event: 'REFUND_SUCCEEDED, nested wrapper + api_source' },
36
- { file: 'refund_succeeded_nested_no_api_source.json', event: 'REFUND_SUCCEEDED, nested wrapper, no api_source' }
37
- ].freeze
38
-
39
- # Payload for the webhook.verify contract check. The signature is NOT hardcoded:
40
- # verify() HMAC-signs JSON.dump(data) with the configured client_secret, so the
41
- # suite recomputes the expected signature for whatever secret it configured.
42
- # Fixed pseudo IDs, not real merchant data.
43
- WEBHOOK_DATA = {
44
- customer: 'cus-000000000000000000',
45
- created_at: '2024-11-29T02:16:12.168127Z',
46
- activated_at: '2024-11-29T02:16:18.040142301Z',
47
- merchant_name: 'TestMerchant1'
48
- }.freeze
49
-
50
- # Mirrors the e2e credential env vars. When unset, the live-API healthcheck is
51
- # skipped so the offline checks still run (e.g. in CI without a reachable backend).
52
- CLIENT_ID = ENV['MERCHANT_CLIENT_ID'] || 'compat-client-id'
53
- CLIENT_SECRET = ENV['MERCHANT_CLIENT_SECRET'] || 'compat-client-secret'
54
- HAS_API_CREDS = !(ENV['MERCHANT_CLIENT_ID'].to_s.empty? || ENV['MERCHANT_CLIENT_SECRET'].to_s.empty?)
55
-
56
- # Fixtures live in the language-neutral packages/sdk/compatibility/testdata/
57
- # directory so every SDK harness consumes the same backend records.
58
- def self.testdata_path(file)
59
- File.join(__dir__, '..', '..', '..', 'compatibility', 'testdata', file)
60
- end
61
-
62
- # The actual checks. A version directory's shim mixes this into a
63
- # Test::Unit::TestCase, so test/unit auto-discovers every `test_*` method.
64
- module Tests
65
- def load_fixture(file)
66
- JSON.parse(File.read(JammCompat.testdata_path(file)), symbolize_names: true)
67
- end
68
-
69
- def configure!
70
- Jamm.configure(
71
- client_id: JammCompat::CLIENT_ID,
72
- client_secret: JammCompat::CLIENT_SECRET,
73
- env: 'local'
74
- )
75
- end
76
-
77
- # config -- expected in every published version.
78
- def test_config_round_trips_local_environment
79
- omit('Jamm.configure absent in this version') unless Jamm.respond_to?(:configure)
80
- configure!
81
- omit('Jamm.environment reader absent in this version') unless Jamm.respond_to?(:environment)
82
- assert_equal('local', Jamm.environment)
83
- end
84
-
85
- # healthcheck -- hits the live local API (api.jamm.test), so it needs creds and
86
- # a reachable backend; skipped otherwise.
87
- def test_healthcheck_pings_api
88
- unless defined?(Jamm::Healthcheck) && Jamm::Healthcheck.respond_to?(:ping)
89
- omit('healthcheck service absent in this version')
90
- end
91
- omit('MERCHANT_CLIENT_* not set; live API check skipped') unless JammCompat::HAS_API_CREDS
92
-
93
- configure!
94
- res = Jamm::Healthcheck.ping
95
- assert_not_nil(res)
96
- assert_true(res.ok)
97
- end
98
-
99
- # webhook.verify -- offline signing-contract check: recompute the signature the
100
- # SDK expects, confirm verify() accepts it, then confirm a tampered (but
101
- # well-formed) signature is rejected.
102
- def test_webhook_verify_accepts_valid_and_rejects_tampered
103
- unless defined?(Jamm::Webhook) && Jamm::Webhook.respond_to?(:verify)
104
- omit('webhook.verify absent in this version')
105
- end
106
-
107
- configure!
108
- digest = OpenSSL::HMAC.hexdigest(
109
- OpenSSL::Digest.new('sha256'),
110
- JammCompat::CLIENT_SECRET,
111
- JSON.dump(JammCompat::WEBHOOK_DATA)
112
- )
113
-
114
- assert_nothing_raised do
115
- Jamm::Webhook.verify(data: JammCompat::WEBHOOK_DATA, signature: "sha256=#{digest}")
116
- end
117
-
118
- assert_raise do
119
- Jamm::Webhook.verify(data: JammCompat::WEBHOOK_DATA, signature: "sha256=#{'0' * 64}")
120
- end
121
- end
122
-
123
- # webhook.parse forward-compat -- pretends the backend is sending current-day
124
- # records that carry api_source and the nested refund wrapper. Every
125
- # parse-capable version MUST decode the core ChargeMessage and ignore fields it
126
- # predates.
127
- #
128
- # NOTE: there is intentionally no rescue here. A version that *has* parse but
129
- # throws on these records is out of sync with the API -- that failure is the
130
- # signal, not an accepted outcome (mirrors the Node harness, where only the
131
- # latest version passes). Only a version with no parse capability at all is
132
- # omitted.
133
- JammCompat::PARSE_FIXTURES.each do |fx|
134
- slug = fx[:file].sub(/\.json\z/, '')
135
- define_method("test_webhook_parse_tolerates_#{slug}") do
136
- unless defined?(Jamm::Webhook) && Jamm::Webhook.respond_to?(:parse)
137
- omit('webhook.parse absent in this version')
138
- end
139
-
140
- msg = Jamm::Webhook.parse(load_fixture(fx[:file]))
141
- assert_equal(JammCompat::EXPECTED[:id], msg.content.id, fx[:event])
142
- assert_equal(JammCompat::EXPECTED[:customer], msg.content.customer, fx[:event])
143
- end
144
- end
145
- end
146
- end
@@ -1,7 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/Gemfile.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=__VERSION__` from packages/sdk/ruby/compatibility.
4
- source 'https://rubygems.org'
5
-
6
- gem 'jamm', '__VERSION__'
7
- gem 'test-unit', '~> 3.0'
@@ -1,16 +0,0 @@
1
- # frozen_string_literal: true
2
- # Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
3
- # Regenerate with `make add VER=__VERSION__` from packages/sdk/ruby/compatibility.
4
- #
5
- # Installs the published jamm@__VERSION__ (pinned in the sibling Gemfile) and runs
6
- # the shared backward-compat suite against it. Requiring 'jamm' here -- under this
7
- # directory's bundle -- is what makes bundler resolve it to *this* pinned version.
8
- require 'jamm'
9
-
10
- require_relative '../shared/suite'
11
-
12
- class CompatTest < Test::Unit::TestCase
13
- include JammCompat::Tests
14
-
15
- SDK_VERSION = '__VERSION__'
16
- end