didit-sdk 2.19.0 → 2.20.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: ed1ba51f92decf32fcb0a2fbdcb154d4e5ea378fc930f3679db6a7d1a5cfb585
4
- data.tar.gz: f7f2b67a5e21885e87ce6f80b51f76c43227edc8b171362aab2564831b77b04b
3
+ metadata.gz: 386e86938a0165b91be256b1890eb68d82e94f766118555be4edc4c95b65e99c
4
+ data.tar.gz: c9ec401cabf274672f67416c706d0a9667740bea0ab2af3c10c27e60619ee0e4
5
5
  SHA512:
6
- metadata.gz: 90e6bf362be7b9d13eb148eb03a843133addcbdc78ded98fd23b617213939b731e909ae31527b3ae0d2d7e1f5cd699f5a85b6f97c019110ddbac3b1324df4d5d
7
- data.tar.gz: 0a8f5572c2d2473df7e93fe5b131c1163a6671fe27a44129c48ead575e657d702314e8b5ea356eb363aa6c1a5063e247557607fc9bde40588583d79973e4a205
6
+ metadata.gz: 4e7824c2658bff991a5e735a8064f6e27c5554654fab55a20156c8aa6a7a7a46fee1954ccd95bbf64a4ba03e408dbfbbf8b4832f7dff367d1cd0e1a94020e474
7
+ data.tar.gz: 6565ed0d918c746a1fe369226a68c3174875d3d689c03c9c6f8b7c671b2f251b4c385682630de27cc2264bbe8ade2e711ec9c9749b3886a9d01852ea90b648d1
data/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.20.1](https://github.com/didit-protocol/sdk-ruby/compare/v2.20.0...v2.20.1) (2026-11-14)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * refuse an idempotency key that is not printable ASCII before any request ([#81](https://github.com/didit-protocol/sdk-ruby/issues/81)) ([dd351a8](https://github.com/didit-protocol/sdk-ruby/commit/dd351a8e93803fcec2bf70c341291025296c0255))
9
+
10
+ ## [2.20.0](https://github.com/didit-protocol/sdk-ruby/compare/v2.19.0...v2.20.0) (2026-11-14)
11
+
12
+
13
+ ### Features
14
+
15
+ * per-request idempotency key ([#66](https://github.com/didit-protocol/sdk-ruby/issues/66)) ([896586c](https://github.com/didit-protocol/sdk-ruby/commit/896586c7083049d43ebf0b27b7d39cf5623ab36d))
16
+
3
17
  ## [2.19.0](https://github.com/didit-protocol/sdk-ruby/compare/v2.18.0...v2.19.0) (2026-11-14)
4
18
 
5
19
 
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,12 @@ 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
+ PRINTABLE_ASCII = /\A(?:[!-~]|[!-~][ -~]*[!-~])\z/
27
+ KEY_METHODS = %i[post put patch delete].freeze
28
+ RETRYABLE_WITH_KEY = %i[post patch].freeze
24
29
  UNRESERVED = /[^A-Za-z0-9\-._~]/
25
30
 
26
31
  module_function
@@ -41,10 +46,23 @@ module Didit
41
46
  max_retries: Config.check_max_retries(opts.fetch(:max_retries, config.max_retries)),
42
47
  extra_headers: opts[:extra_headers] || {},
43
48
  extra_query: opts[:extra_query] || {},
44
- extra_body: opts[:extra_body] || {}
49
+ extra_body: opts[:extra_body] || {},
50
+ idempotency_key: opts.key?(:idempotency_key) ? check_idempotency_key(opts[:idempotency_key]) : nil
45
51
  }
46
52
  end
47
53
 
54
+ # The key must be a String of 1 to 255 printable ASCII characters (space to "~") that neither start nor
55
+ # end with a space: it travels as an HTTP header value that the server trims.
56
+ def check_idempotency_key(value)
57
+ unless value.is_a?(String) && value.length.between?(1, IDEMPOTENCY_KEY_MAX) && value.match?(PRINTABLE_ASCII)
58
+ shown = value.is_a?(String) ? "a String of #{value.length} characters" : value.inspect
59
+ raise ConfigurationError, "idempotency_key must be a String of 1 to #{IDEMPOTENCY_KEY_MAX} printable ASCII " \
60
+ "characters that neither start nor end with a space, got #{shown}."
61
+ end
62
+
63
+ value
64
+ end
65
+
48
66
  # @return [Prepared]
49
67
  def prepare(config, http_method, path, opts, path_params: {}, query: nil, body: nil, encoding: :json,
50
68
  file_fields: [], headers: {}, auth: :api_key, api: :verification, scope: nil,
@@ -58,8 +76,9 @@ module Didit
58
76
  body_bytes, content_type = encode_body(body, opts[:extra_body], encoding, file_fields)
59
77
  Prepared.new(
60
78
  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]),
79
+ headers: build_headers(config, auth, accept: accept, content_type: content_type,
80
+ op_headers: headers, extra_headers: opts[:extra_headers],
81
+ http_method: http_method, idempotency_key: opts[:idempotency_key]),
63
82
  body: body_bytes, timeout: opts[:timeout], max_retries: opts[:max_retries],
64
83
  redact: [config.api_key, config.account_token].compact
65
84
  )
@@ -177,16 +196,38 @@ module Didit
177
196
  end
178
197
  end
179
198
 
180
- def build_headers(config, auth, accept:, content_type:, op_headers:, extra_headers:)
199
+ def build_headers(config, auth, accept:, content_type:, op_headers:, extra_headers:, http_method: :post,
200
+ idempotency_key: nil)
181
201
  # @type var pairs: Array[[untyped, untyped]]
182
202
  pairs = [["Accept", accept], ["User-Agent", Util.user_agent], ["X-Didit-Client", Util.client_header]]
183
- pairs.concat(config.default_headers.to_a)
203
+ # A client-wide default Idempotency-Key never counts.
204
+ pairs.concat(config.default_headers.to_a.reject { |name, _| idempotency_name?(name) })
184
205
  credential = credential_header(config, auth)
185
206
  pairs << credential if credential
186
207
  pairs << ["Content-Type", content_type] if content_type
187
208
  pairs.concat(op_headers.reject { |_, value| value.equal?(OMIT) }.to_a)
188
209
  pairs.concat(extra_headers.to_a)
189
- merge_headers(pairs)
210
+ pairs << [IDEMPOTENCY_HEADER, idempotency_key] if idempotency_key
211
+ merge_headers(with_effective_key(pairs, http_method))
212
+ end
213
+
214
+ def idempotency_name?(name)
215
+ name.to_s.casecmp?(IDEMPOTENCY_HEADER)
216
+ end
217
+
218
+ # Collapses every Idempotency-Key pair into the effective key (the last one; nil removes it),
219
+ # validates it whatever its source, and sends it only on the allow-listed methods.
220
+ def with_effective_key(pairs, http_method)
221
+ keyed, others = pairs.partition { |name, _| idempotency_name?(name) }
222
+ effective = keyed.empty? ? nil : keyed.last&.last
223
+ return others if effective.nil?
224
+
225
+ check_idempotency_key(effective)
226
+ return others unless KEY_METHODS.include?(http_method)
227
+
228
+ # @type var pair: [untyped, untyped]
229
+ pair = [IDEMPOTENCY_HEADER, effective]
230
+ others + [pair]
190
231
  end
191
232
 
192
233
  # Header names are case-insensitive: a later value replaces an earlier one whatever its
@@ -258,7 +299,7 @@ module Didit
258
299
  def retry_delay(config, prepared, attempt, retries)
259
300
  left = prepared.max_retries - retries
260
301
  if (failure = attempt.failure)
261
- return nil if attempt.streamed || left <= 0 || !retry_failure?(prepared.http_method, failure)
302
+ return nil if attempt.streamed || left <= 0 || !retry_failure?(prepared, failure)
262
303
 
263
304
  delay = backoff(retries)
264
305
  Log.retry(config, prepared, failure.timeout? ? "timed out" : failure.error.class.name, delay, left)
@@ -268,22 +309,48 @@ module Didit
268
309
  return nil unless response
269
310
 
270
311
  Log.response(config, prepared, response, attempt.elapsed)
271
- return nil if left <= 0 || !retry_status?(prepared.http_method, response.status)
312
+ return nil if left <= 0 || !retry_status?(prepared, response)
272
313
 
273
314
  delay = retry_after(response.headers["retry-after"]) || backoff(retries)
274
315
  Log.retry(config, prepared, "HTTP #{response.status}", delay, left)
275
316
  delay
276
317
  end
277
318
 
278
- def retry_status?(http_method, status)
319
+ def retry_status?(prepared, response)
320
+ status = response.status
279
321
  return true if status == 429
280
- return false unless IDEMPOTENT.include?(http_method)
322
+ return key_in_progress?(response) if status == 409 && carries_key?(prepared)
323
+ return false unless safe_to_repeat?(prepared)
281
324
 
282
325
  status == 408 || status.between?(500, 599)
283
326
  end
284
327
 
285
- def retry_failure?(http_method, failure)
286
- !failure.sent || IDEMPOTENT.include?(http_method)
328
+ def retry_failure?(prepared, failure)
329
+ !failure.sent || safe_to_repeat?(prepared)
330
+ end
331
+
332
+ # GET, HEAD, PUT and DELETE, and a POST or PATCH that carries an Idempotency-Key.
333
+ def safe_to_repeat?(prepared)
334
+ IDEMPOTENT.include?(prepared.http_method) || keyed?(prepared)
335
+ end
336
+
337
+ # Whether the key makes this method retryable: only POST and PATCH (the others already are).
338
+ def keyed?(prepared)
339
+ RETRYABLE_WITH_KEY.include?(prepared.http_method) && carries_key?(prepared)
340
+ end
341
+
342
+ # Whether the request carries an Idempotency-Key (any of the four allow-listed methods).
343
+ def carries_key?(prepared)
344
+ KEY_METHODS.include?(prepared.http_method) &&
345
+ prepared.headers.keys.any? { |name| name.casecmp?(IDEMPOTENCY_HEADER) }
346
+ end
347
+
348
+ # A 409 whose JSON body says the first request with this key is still running.
349
+ def key_in_progress?(response)
350
+ body = JSON.parse(response.body.to_s)
351
+ body.is_a?(Hash) && body["code"] == "idempotency_key_in_progress"
352
+ rescue JSON::ParserError
353
+ false
287
354
  end
288
355
 
289
356
  # 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.1" # x-release-please-version
5
5
  end
@@ -105,13 +105,19 @@ 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
+ PRINTABLE_ASCII: Regexp
119
+ KEY_METHODS: Array[Symbol]
120
+ RETRYABLE_WITH_KEY: Array[Symbol]
115
121
  UNRESERVED: Regexp
116
122
 
117
123
  def self?.options: (Config config, untyped raw) -> options
@@ -119,6 +125,9 @@ module Didit
119
125
  ?query: Hash[String, untyped]?, ?body: untyped, ?encoding: Symbol, ?file_fields: Array[String],
120
126
  ?headers: Hash[String, untyped], ?auth: Symbol, ?api: Symbol, ?scope: Symbol?,
121
127
  ?accept: String) -> Prepared
128
+ def self?.check_idempotency_key: (untyped value) -> String
129
+ def self?.idempotency_name?: (untyped name) -> bool
130
+ def self?.with_effective_key: (Array[[untyped, untyped]] pairs, Symbol http_method) -> Array[[untyped, untyped]]
122
131
  def self?.scoped: (Config config, Hash[String, untyped] path_params) -> Hash[String, untyped]
123
132
  def self?.check_credentials: (Config config, Symbol auth) -> void
124
133
  def self?.encode_path: (String path, Hash[String, untyped] params) -> String
@@ -129,7 +138,8 @@ module Didit
129
138
  def self?.encode_body: (untyped body, untyped extra_body, Symbol encoding, Array[String] file_fields) -> [String?, String?]
130
139
  def self?.json_value: (untyped value) -> untyped
131
140
  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]
141
+ op_headers: Hash[String, untyped], extra_headers: Hash[untyped, untyped],
142
+ ?http_method: Symbol, ?idempotency_key: String?) -> Hash[String, String]
133
143
  def self?.merge_headers: (Array[[untyped, untyped]] pairs) -> Hash[String, String]
134
144
  def self?.credential_header: (Config config, Symbol auth) -> [String, String]?
135
145
  class Attempt < Struct[untyped]
@@ -144,8 +154,12 @@ module Didit
144
154
  def self?.perform: (Config config, Transport transport, Prepared prepared) ?{ (String chunk) -> void } -> Result
145
155
  def self?.attempt: (Transport transport, Prepared prepared) ?{ (String chunk) -> void } -> Attempt
146
156
  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
157
+ def self?.retry_status?: (Prepared prepared, Transport::Response response) -> bool
158
+ def self?.retry_failure?: (Prepared prepared, Transport::Failure failure) -> bool
159
+ def self?.safe_to_repeat?: (Prepared prepared) -> bool
160
+ def self?.keyed?: (Prepared prepared) -> bool
161
+ def self?.carries_key?: (Prepared prepared) -> bool
162
+ def self?.key_in_progress?: (Transport::Response response) -> bool
149
163
  def self?.backoff: (Integer retries_taken) -> Float
150
164
  def self?.retry_after: (String? value, ?now: Time) -> Float?
151
165
  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.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Didit