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 +4 -4
- data/CHANGELOG.md +14 -0
- data/README.md +11 -1
- data/lib/didit/internal/request.rb +80 -13
- data/lib/didit/version.rb +1 -1
- data/sig/didit/internal.rbs +18 -4
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 386e86938a0165b91be256b1890eb68d82e94f766118555be4edc4c95b65e99c
|
|
4
|
+
data.tar.gz: c9ec401cabf274672f67416c706d0a9667740bea0ab2af3c10c27e60619ee0e4
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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?(
|
|
319
|
+
def retry_status?(prepared, response)
|
|
320
|
+
status = response.status
|
|
279
321
|
return true if status == 429
|
|
280
|
-
return
|
|
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?(
|
|
286
|
-
!failure.sent ||
|
|
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
data/sig/didit/internal.rbs
CHANGED
|
@@ -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]
|
|
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?: (
|
|
148
|
-
def self?.retry_failure?: (
|
|
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?
|