didit-sdk 2.19.0 → 2.20.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: ed1ba51f92decf32fcb0a2fbdcb154d4e5ea378fc930f3679db6a7d1a5cfb585
4
- data.tar.gz: f7f2b67a5e21885e87ce6f80b51f76c43227edc8b171362aab2564831b77b04b
3
+ metadata.gz: 58596e10eb50e7a57f33c7024c52a0201b68090c2ce1724ed0a95d9bb43787ae
4
+ data.tar.gz: 0655b223441a6aad276de0cf8d4d85fa966e20898024a808213363e9920b9124
5
5
  SHA512:
6
- metadata.gz: 90e6bf362be7b9d13eb148eb03a843133addcbdc78ded98fd23b617213939b731e909ae31527b3ae0d2d7e1f5cd699f5a85b6f97c019110ddbac3b1324df4d5d
7
- data.tar.gz: 0a8f5572c2d2473df7e93fe5b131c1163a6671fe27a44129c48ead575e657d702314e8b5ea356eb363aa6c1a5063e247557607fc9bde40588583d79973e4a205
6
+ metadata.gz: 730e39c0fff1151cda0e223a56a0a721fed943470c391f14d2be78fa906322196bfa1651ae740021d38aab3be75e693da50cb63587db437abc6a2fc35d04ee2e
7
+ data.tar.gz: 20d98d5fdefcc2861614f80357a060f2be272a0e5b3d5b61186188f50aee83641c200c05ad78141349d310cf1894915691d66192e3ae4d57c9603032cc2b66d9
data/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.20.0](https://github.com/didit-protocol/sdk-ruby/compare/v2.19.0...v2.20.0) (2026-11-14)
4
+
5
+
6
+ ### Features
7
+
8
+ * per-request idempotency key ([#66](https://github.com/didit-protocol/sdk-ruby/issues/66)) ([896586c](https://github.com/didit-protocol/sdk-ruby/commit/896586c7083049d43ebf0b27b7d39cf5623ab36d))
9
+
3
10
  ## [2.19.0](https://github.com/didit-protocol/sdk-ruby/compare/v2.18.0...v2.19.0) (2026-11-14)
4
11
 
5
12
 
data/README.md CHANGED
@@ -72,7 +72,7 @@ didit = Didit::Client.new(
72
72
 
73
73
  - One client per process is the intended use. It is thread safe, keeps connections open per host, and a forked child never reuses its parent's connections.
74
74
  - `with_options` returns a copy with some options changed that shares the connections: `didit.with_options(timeout: 5, max_retries: 0)`.
75
- - Every method takes `request_options:` for one call: `{ timeout:, max_retries:, extra_headers:, extra_query:, extra_body: }`.
75
+ - Every method takes `request_options:` for one call: `{ timeout:, max_retries:, extra_headers:, extra_query:, extra_body:, idempotency_key: }`.
76
76
  - Application-scoped methods (all of `cases`, `networks`, `regulatory_reports`, `report_templates` and `business_sessions`, and some of `sessions`, `users`, `businesses` and `transactions`): the SDK fills `organization_id` and `application_id` from the client, and raises `Didit::ConfigurationError` before sending when either is missing.
77
77
  - The API key is sent only to `base_url`. It never appears in logs, error messages or error bodies.
78
78
 
@@ -136,6 +136,16 @@ Failed requests are retried up to `max_retries` times (default 2) with exponenti
136
136
  GET, HEAD, PUT and DELETE are retried on connection errors, timeouts, 408, 429 and 5xx.
137
137
  POST and PATCH are retried only on 429 and when the connection failed before the request was sent, never after it may have reached the server.
138
138
 
139
+ ### Idempotency
140
+
141
+ The `idempotency_key` request option sends an `Idempotency-Key` header, so repeating the same operation with the same key never runs or bills it twice.
142
+
143
+ ```ruby
144
+ didit.sessions.create(workflow_id: "wf", request_options: { idempotency_key: "signup-8c1f" })
145
+ ```
146
+
147
+ With a key, POST and PATCH are retried like GET.
148
+
139
149
  ## Pagination
140
150
 
141
151
  ```ruby
@@ -20,7 +20,11 @@ module Didit
20
20
  INITIAL_RETRY_DELAY = 0.5
21
21
  MAX_RETRY_DELAY = 8.0
22
22
  MAX_RETRY_AFTER = 60.0
23
- OPTION_KEYS = %i[timeout max_retries extra_headers extra_query extra_body].freeze
23
+ OPTION_KEYS = %i[timeout max_retries extra_headers extra_query extra_body idempotency_key].freeze
24
+ IDEMPOTENCY_HEADER = "Idempotency-Key"
25
+ IDEMPOTENCY_KEY_MAX = 255
26
+ KEY_METHODS = %i[post put patch delete].freeze
27
+ RETRYABLE_WITH_KEY = %i[post patch].freeze
24
28
  UNRESERVED = /[^A-Za-z0-9\-._~]/
25
29
 
26
30
  module_function
@@ -41,10 +45,22 @@ module Didit
41
45
  max_retries: Config.check_max_retries(opts.fetch(:max_retries, config.max_retries)),
42
46
  extra_headers: opts[:extra_headers] || {},
43
47
  extra_query: opts[:extra_query] || {},
44
- extra_body: opts[:extra_body] || {}
48
+ extra_body: opts[:extra_body] || {},
49
+ idempotency_key: opts.key?(:idempotency_key) ? check_idempotency_key(opts[:idempotency_key]) : nil
45
50
  }
46
51
  end
47
52
 
53
+ # The key must be a String of 1 to 255 characters.
54
+ def check_idempotency_key(value)
55
+ unless value.is_a?(String) && value.length.between?(1, IDEMPOTENCY_KEY_MAX)
56
+ shown = value.is_a?(String) ? "a String of #{value.length} characters" : value.inspect
57
+ raise ConfigurationError, "idempotency_key must be a String of 1 to #{IDEMPOTENCY_KEY_MAX} characters, " \
58
+ "got #{shown}."
59
+ end
60
+
61
+ value
62
+ end
63
+
48
64
  # @return [Prepared]
49
65
  def prepare(config, http_method, path, opts, path_params: {}, query: nil, body: nil, encoding: :json,
50
66
  file_fields: [], headers: {}, auth: :api_key, api: :verification, scope: nil,
@@ -58,8 +74,9 @@ module Didit
58
74
  body_bytes, content_type = encode_body(body, opts[:extra_body], encoding, file_fields)
59
75
  Prepared.new(
60
76
  http_method: http_method, uri: uri, origin: Util.origin(base),
61
- headers: build_headers(config, auth, accept: accept, content_type: content_type, op_headers: headers,
62
- extra_headers: opts[:extra_headers]),
77
+ headers: build_headers(config, auth, accept: accept, content_type: content_type,
78
+ op_headers: headers, extra_headers: opts[:extra_headers],
79
+ http_method: http_method, idempotency_key: opts[:idempotency_key]),
63
80
  body: body_bytes, timeout: opts[:timeout], max_retries: opts[:max_retries],
64
81
  redact: [config.api_key, config.account_token].compact
65
82
  )
@@ -177,16 +194,38 @@ module Didit
177
194
  end
178
195
  end
179
196
 
180
- def build_headers(config, auth, accept:, content_type:, op_headers:, extra_headers:)
197
+ def build_headers(config, auth, accept:, content_type:, op_headers:, extra_headers:, http_method: :post,
198
+ idempotency_key: nil)
181
199
  # @type var pairs: Array[[untyped, untyped]]
182
200
  pairs = [["Accept", accept], ["User-Agent", Util.user_agent], ["X-Didit-Client", Util.client_header]]
183
- pairs.concat(config.default_headers.to_a)
201
+ # A client-wide default Idempotency-Key never counts.
202
+ pairs.concat(config.default_headers.to_a.reject { |name, _| idempotency_name?(name) })
184
203
  credential = credential_header(config, auth)
185
204
  pairs << credential if credential
186
205
  pairs << ["Content-Type", content_type] if content_type
187
206
  pairs.concat(op_headers.reject { |_, value| value.equal?(OMIT) }.to_a)
188
207
  pairs.concat(extra_headers.to_a)
189
- merge_headers(pairs)
208
+ pairs << [IDEMPOTENCY_HEADER, idempotency_key] if idempotency_key
209
+ merge_headers(with_effective_key(pairs, http_method))
210
+ end
211
+
212
+ def idempotency_name?(name)
213
+ name.to_s.casecmp?(IDEMPOTENCY_HEADER)
214
+ end
215
+
216
+ # Collapses every Idempotency-Key pair into the effective key (the last one; nil removes it),
217
+ # validates it whatever its source, and sends it only on the allow-listed methods.
218
+ def with_effective_key(pairs, http_method)
219
+ keyed, others = pairs.partition { |name, _| idempotency_name?(name) }
220
+ effective = keyed.empty? ? nil : keyed.last&.last
221
+ return others if effective.nil?
222
+
223
+ check_idempotency_key(effective)
224
+ return others unless KEY_METHODS.include?(http_method)
225
+
226
+ # @type var pair: [untyped, untyped]
227
+ pair = [IDEMPOTENCY_HEADER, effective]
228
+ others + [pair]
190
229
  end
191
230
 
192
231
  # Header names are case-insensitive: a later value replaces an earlier one whatever its
@@ -258,7 +297,7 @@ module Didit
258
297
  def retry_delay(config, prepared, attempt, retries)
259
298
  left = prepared.max_retries - retries
260
299
  if (failure = attempt.failure)
261
- return nil if attempt.streamed || left <= 0 || !retry_failure?(prepared.http_method, failure)
300
+ return nil if attempt.streamed || left <= 0 || !retry_failure?(prepared, failure)
262
301
 
263
302
  delay = backoff(retries)
264
303
  Log.retry(config, prepared, failure.timeout? ? "timed out" : failure.error.class.name, delay, left)
@@ -268,22 +307,48 @@ module Didit
268
307
  return nil unless response
269
308
 
270
309
  Log.response(config, prepared, response, attempt.elapsed)
271
- return nil if left <= 0 || !retry_status?(prepared.http_method, response.status)
310
+ return nil if left <= 0 || !retry_status?(prepared, response)
272
311
 
273
312
  delay = retry_after(response.headers["retry-after"]) || backoff(retries)
274
313
  Log.retry(config, prepared, "HTTP #{response.status}", delay, left)
275
314
  delay
276
315
  end
277
316
 
278
- def retry_status?(http_method, status)
317
+ def retry_status?(prepared, response)
318
+ status = response.status
279
319
  return true if status == 429
280
- return false unless IDEMPOTENT.include?(http_method)
320
+ return key_in_progress?(response) if status == 409 && carries_key?(prepared)
321
+ return false unless safe_to_repeat?(prepared)
281
322
 
282
323
  status == 408 || status.between?(500, 599)
283
324
  end
284
325
 
285
- def retry_failure?(http_method, failure)
286
- !failure.sent || IDEMPOTENT.include?(http_method)
326
+ def retry_failure?(prepared, failure)
327
+ !failure.sent || safe_to_repeat?(prepared)
328
+ end
329
+
330
+ # GET, HEAD, PUT and DELETE, and a POST or PATCH that carries an Idempotency-Key.
331
+ def safe_to_repeat?(prepared)
332
+ IDEMPOTENT.include?(prepared.http_method) || keyed?(prepared)
333
+ end
334
+
335
+ # Whether the key makes this method retryable: only POST and PATCH (the others already are).
336
+ def keyed?(prepared)
337
+ RETRYABLE_WITH_KEY.include?(prepared.http_method) && carries_key?(prepared)
338
+ end
339
+
340
+ # Whether the request carries an Idempotency-Key (any of the four allow-listed methods).
341
+ def carries_key?(prepared)
342
+ KEY_METHODS.include?(prepared.http_method) &&
343
+ prepared.headers.keys.any? { |name| name.casecmp?(IDEMPOTENCY_HEADER) }
344
+ end
345
+
346
+ # A 409 whose JSON body says the first request with this key is still running.
347
+ def key_in_progress?(response)
348
+ body = JSON.parse(response.body.to_s)
349
+ body.is_a?(Hash) && body["code"] == "idempotency_key_in_progress"
350
+ rescue JSON::ParserError
351
+ false
287
352
  end
288
353
 
289
354
  # Exponential backoff from 0.5 s with full jitter, capped at 8 s.
data/lib/didit/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Didit
4
- VERSION = "2.19.0" # x-release-please-version
4
+ VERSION = "2.20.0" # x-release-please-version
5
5
  end
@@ -105,13 +105,18 @@ module Didit
105
105
  end
106
106
 
107
107
  type options = { timeout: Float, max_retries: Integer, extra_headers: Hash[untyped, untyped],
108
- extra_query: Hash[untyped, untyped], extra_body: Hash[untyped, untyped] }
108
+ extra_query: Hash[untyped, untyped], extra_body: Hash[untyped, untyped],
109
+ idempotency_key: String? }
109
110
 
110
111
  IDEMPOTENT: Array[Symbol]
111
112
  INITIAL_RETRY_DELAY: Float
112
113
  MAX_RETRY_DELAY: Float
113
114
  MAX_RETRY_AFTER: Float
114
115
  OPTION_KEYS: Array[Symbol]
116
+ IDEMPOTENCY_HEADER: String
117
+ IDEMPOTENCY_KEY_MAX: Integer
118
+ KEY_METHODS: Array[Symbol]
119
+ RETRYABLE_WITH_KEY: Array[Symbol]
115
120
  UNRESERVED: Regexp
116
121
 
117
122
  def self?.options: (Config config, untyped raw) -> options
@@ -119,6 +124,9 @@ module Didit
119
124
  ?query: Hash[String, untyped]?, ?body: untyped, ?encoding: Symbol, ?file_fields: Array[String],
120
125
  ?headers: Hash[String, untyped], ?auth: Symbol, ?api: Symbol, ?scope: Symbol?,
121
126
  ?accept: String) -> Prepared
127
+ def self?.check_idempotency_key: (untyped value) -> String
128
+ def self?.idempotency_name?: (untyped name) -> bool
129
+ def self?.with_effective_key: (Array[[untyped, untyped]] pairs, Symbol http_method) -> Array[[untyped, untyped]]
122
130
  def self?.scoped: (Config config, Hash[String, untyped] path_params) -> Hash[String, untyped]
123
131
  def self?.check_credentials: (Config config, Symbol auth) -> void
124
132
  def self?.encode_path: (String path, Hash[String, untyped] params) -> String
@@ -129,7 +137,8 @@ module Didit
129
137
  def self?.encode_body: (untyped body, untyped extra_body, Symbol encoding, Array[String] file_fields) -> [String?, String?]
130
138
  def self?.json_value: (untyped value) -> untyped
131
139
  def self?.build_headers: (Config config, Symbol auth, accept: String, content_type: String?,
132
- op_headers: Hash[String, untyped], extra_headers: Hash[untyped, untyped]) -> Hash[String, String]
140
+ op_headers: Hash[String, untyped], extra_headers: Hash[untyped, untyped],
141
+ ?http_method: Symbol, ?idempotency_key: String?) -> Hash[String, String]
133
142
  def self?.merge_headers: (Array[[untyped, untyped]] pairs) -> Hash[String, String]
134
143
  def self?.credential_header: (Config config, Symbol auth) -> [String, String]?
135
144
  class Attempt < Struct[untyped]
@@ -144,8 +153,12 @@ module Didit
144
153
  def self?.perform: (Config config, Transport transport, Prepared prepared) ?{ (String chunk) -> void } -> Result
145
154
  def self?.attempt: (Transport transport, Prepared prepared) ?{ (String chunk) -> void } -> Attempt
146
155
  def self?.retry_delay: (Config config, Prepared prepared, Attempt attempt, Integer retries) -> Float?
147
- def self?.retry_status?: (Symbol http_method, Integer status) -> bool
148
- def self?.retry_failure?: (Symbol http_method, Transport::Failure failure) -> bool
156
+ def self?.retry_status?: (Prepared prepared, Transport::Response response) -> bool
157
+ def self?.retry_failure?: (Prepared prepared, Transport::Failure failure) -> bool
158
+ def self?.safe_to_repeat?: (Prepared prepared) -> bool
159
+ def self?.keyed?: (Prepared prepared) -> bool
160
+ def self?.carries_key?: (Prepared prepared) -> bool
161
+ def self?.key_in_progress?: (Transport::Response response) -> bool
149
162
  def self?.backoff: (Integer retries_taken) -> Float
150
163
  def self?.retry_after: (String? value, ?now: Time) -> Float?
151
164
  def self?.http_date_seconds: (String text, Time now) -> Float?
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: didit-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.19.0
4
+ version: 2.20.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Didit