kompressr-sdk 0.1.0 → 0.2.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: 6105efcaa3539d479fb065278d443dc2be27ca97a39ca1099be93dd5b74834d1
4
- data.tar.gz: a4acb4f82539d245b315a7966b6370c0d9e794f64056c54e6374e8f59fbe04b8
3
+ metadata.gz: 9ba0796199657541189514cbb17e425a42b52179c50cd4a342a500040a416a03
4
+ data.tar.gz: a74a59cc64cfe7d40a93971572d404e96441862e95eed8d3836a8a0f17617a8d
5
5
  SHA512:
6
- metadata.gz: c488eee0f85d32ccb024694c74a40119c5b974205b22e89b9e0cf1ade554cf68dc45092f735939143d296ae5a88bf1ef056f04d0696d54b0a5982748eda0ab79
7
- data.tar.gz: 5accd48a87e135c7a71e64a7a25c3bd9b2ed7f2d41e2e57753e8ac9971f3c3640238d70bafdcfa9a626f8932438850c5bee42ce1bbda808ff91d7dd0c97f731e
6
+ metadata.gz: 3cf70bf91f8063b0c3486e07571cba88130e6cd296f8e7677994410f9bc3b4bda6f1b089329ca75e20fd263613c645c3ccc0cc1907a316243b0edf39ac398a43
7
+ data.tar.gz: 9bd10927abdd22130ab5fabda70ce658aab38b5e458b7ab2b1ea46863d0bc2ea784466134cc5042f991de85b7a3752248a86fc1c0f1577138063b9a5f928ab50
data/API.md CHANGED
@@ -105,7 +105,7 @@ IssuedKey exposes `id`, `key_id`, optional `upload_key`, and `reveal_api_key`. T
105
105
 
106
106
  Only GET network failures and HTTP 429/502/503/504 automatically retry, up to `max_read_retries`. Backoff starts near 250 ms and includes small jitter. Header `Retry-After` (seconds/date) or JSON `retry_after` (seconds) is a minimum delay; enormous values are saturated without an early retry. Deadline/cancellation during backoff retains the latest status and retry delay. Permission denials, malformed data and processing failures are not retryable reads.
107
107
 
108
- Writes are never replayed and redirects are never followed. A write becomes potentially successful when request bytes may have been sent. Losing the response or receiving malformed successful data retains that uncertainty. Upload ID recovery requires valid JSON with `success: true` and valid numeric `data.asset_id`; broken JSON and invalid Unicode do not produce IDs. Single-asset mutations retain the requested ID. Cancellation before dispatch does not claim success.
108
+ Writes are never replayed and redirects are never followed. A write becomes potentially successful when request bytes may have been sent. Losing the response or receiving malformed successful data retains that uncertainty. Upload ID recovery requires a parsed envelope with boolean `success` and valid numeric `data.asset_id`, including failed envelopes and non-2xx responses; broken JSON and invalid Unicode do not produce IDs. A recovered upload ID sets `may_have_succeeded=true` so callers can check retained work without replaying it. Single-asset mutations retain the requested ID. Cancellation before dispatch does not claim success.
109
109
 
110
110
  During body transmission, the client also watches for an early server response. A permission, size-limit or rate-limit rejection can stop the upload before the whole file is sent, while retaining its API status, code and retry hint. Informational responses allow transmission to continue. A disconnect without a usable response still retains write uncertainty.
111
111
 
@@ -118,3 +118,15 @@ The transport uses Socket/OpenSSL nonblocking I/O and a small HTTP/1.1 parser. N
118
118
  DNS uses a process-wide maximum of eight background workers, with no queued resolver jobs. A timed-out/cancelled lookup cannot connect or send a late request. A blocked OS lookup holds its slot until it returns; later hostname requests can time out waiting for admission. Numeric IP origins bypass DNS. At most 64 attempts hold connection slots per process. Waiting for either limit remains inside the same deadline. Addresses are tried sequentially with a share of the remaining budget, preserving hostname/SNI; this can be slower than racing address families. Capacity is reset after a process fork, supporting preloaded applications.
119
119
 
120
120
  File validation/opening and the byte snapshot precede the HTTP deadline. Regular local file reads occur in bounded chunks, but OS/filesystem stalls and arbitrary Ruby thread scheduling are not forcibly interrupted. Local file access errors before dispatch remain normal Ruby filesystem exceptions. The caller supplies trusted local file paths and keeps input files/options unchanged during calls. MRI Ruby 3.2+ is the supported runtime; asynchronous scheduler integration and other Ruby engines are unverified.
121
+
122
+ ## Store original bytes
123
+
124
+ ```ruby
125
+ files.upload_file('archive.zip', passthrough: true)
126
+ ```
127
+
128
+ When enabled on Pro, Growth, Platform or Enterprise, passthrough stores arbitrary original bytes, including empty files, without optimization credits. Default file caps are 250 MiB, 500 MiB, 1 GiB and 2 GiB respectively; account overrides apply. Storage counts one retained copy and bandwidth remains metered. The separate organization rate pool defaults to five times normal non-video limits. Scoped type restrictions must permit File (11).
129
+
130
+ The SDK puts the optional boolean in the URL query, before dispatch; it is never a multipart field. Omitted or false preserves normal uploads. A successful passthrough response is immediately `processed` and includes `passthrough: true`. Quality, format and resizing options do not optimize a passthrough file. The default private-link variant selects its original bytes; AVIF is unavailable.
131
+
132
+ If the server omits or denies the acknowledgment, the SDK raises `INVALID_RESPONSE` and preserves any safely recovered asset ID with write uncertainty. Inspect the existing asset before retrying; the SDK never automatically replays the upload. Normal uploads remain compatible with responses that omit the new field.
data/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0
4
+
5
+ - Add optional passthrough uploads, immediate ready File results, and explicit mode confirmation with safe asset-ID recovery.
6
+ - Preserve validated asset IDs and write uncertainty on partial upload errors, including HTTP 403/409/500, without replaying uploads.
7
+
3
8
  ## 0.1.0
4
9
 
5
10
  - Support MRI Ruby 3.2 and later, including isolated installation of required runtime gems.
data/README.md CHANGED
@@ -11,7 +11,7 @@ Bundler installs the required standard-library gems when your Ruby version bundl
11
11
  Add to your application's Gemfile:
12
12
 
13
13
  ```ruby
14
- gem 'kompressr-sdk', '~> 0.1.0', require: 'kompressr'
14
+ gem 'kompressr-sdk', '~> 0.2.0', require: 'kompressr'
15
15
  ```
16
16
 
17
17
  Run `bundle install`. For a standalone script, install with `gem install kompressr-sdk` and load it with `require 'kompressr'`. The gem declares its Ruby standard-gem dependencies and has no framework dependency.
@@ -144,6 +144,18 @@ bundle install
144
144
  ruby scripts/verify.rb
145
145
  ```
146
146
 
147
- Verification uses local HTTP/TLS fixtures, builds `pkg/kompressr-sdk-0.1.0.gem`, installs it in an isolated gem directory and reruns the regressions against the installed package. It requires no live service credentials. For release verification, run `node scripts/verify-all.mjs ruby` from the repository root instead of the native command; it runs the native verifier plus shared contract, source and archive checks and requires Node.js and Python 3 as well as Ruby.
147
+ Verification uses local HTTP/TLS fixtures, builds `pkg/kompressr-sdk-0.2.0.gem`, installs it in an isolated gem directory and reruns the regressions against the installed package. It requires no live service credentials. For release verification, run `node scripts/verify-all.mjs ruby` from the repository root instead of the native command; it runs the native verifier plus shared contract, source and archive checks and requires Node.js and Python 3 as well as Ruby.
148
148
 
149
149
  Report security issues privately using the repository's [security policy](https://github.com/kompressrcdn/clients/blob/main/SECURITY.md). MIT licensed; see [LICENSE](https://github.com/kompressrcdn/clients/blob/main/sdk-ruby/LICENSE).
150
+
151
+ ## Store original bytes
152
+
153
+ ```ruby
154
+ files.upload_file('archive.zip', passthrough: true)
155
+ ```
156
+
157
+ When enabled on Pro, Growth, Platform or Enterprise, passthrough stores arbitrary original bytes, including empty files, without optimization credits. Default file caps are 250 MiB, 500 MiB, 1 GiB and 2 GiB respectively; account overrides apply. Storage counts one retained copy and bandwidth remains metered. The separate organization rate pool defaults to five times normal non-video limits. Scoped type restrictions must permit File (11).
158
+
159
+ The SDK puts the optional boolean in the URL query, before dispatch; it is never a multipart field. Omitted or false preserves normal uploads. A successful passthrough response is immediately `processed` and includes `passthrough: true`. Quality, format and resizing options do not optimize a passthrough file. The default private-link variant selects its original bytes; AVIF is unavailable.
160
+
161
+ If the server omits or denies the acknowledgment, the SDK raises `INVALID_RESPONSE` and preserves any safely recovered asset ID with write uncertainty. Inspect the existing asset before retrying; the SDK never automatically replays the upload. Normal uploads remain compatible with responses that omit the new field.
@@ -176,7 +176,9 @@ module Kompressr
176
176
  Validation.positive(value, 'expires_in', 604_800)
177
177
  Validation.invalid('Private URL lifetime must be at least 60 seconds.') if value < 60
178
178
  end
179
- def upload_source(source, size, name, visibility: nil, quality: nil, data: nil, private_url_expires_in: nil, timeout: nil, cancel: nil)
179
+ def upload_source(source, size, name, passthrough: nil, visibility: nil, quality: nil, data: nil, private_url_expires_in: nil, timeout: nil, cancel: nil)
180
+ Validation.invalid('passthrough must be a boolean.') unless passthrough.nil? || passthrough.equal?(true) || passthrough.equal?(false)
181
+ path = '/api/upload' + (passthrough.nil? ? '' : "?passthrough=#{passthrough}")
180
182
  fields = {}
181
183
  fields['visibility'] = Validation.enum(visibility, %w[public private], 'visibility') unless visibility.nil?
182
184
  fields['kmp-quality'] = Validation.enum(quality, %w[480p 720p 1080p 4k], 'quality') unless quality.nil?
@@ -186,9 +188,10 @@ module Kompressr
186
188
  fields['private_url_expires_in'] = private_url_expires_in.to_s
187
189
  end
188
190
  body = Internal::Multipart.new(source, size, name, fields)
189
- @transport.request('/api/upload', method: 'POST', multipart: body, upload: true, timeout: timeout, cancel: cancel, recover_upload_id: true) do |value|
191
+ @transport.request(path, method: 'POST', multipart: body, upload: true, timeout: timeout, cancel: cancel, recover_upload_id: true) do |value|
190
192
  response = Validation.success(value)
191
193
  result = Validation.upload(response['data'], accepted: true)
194
+ Validation.bad('Passthrough mode was not confirmed; inspect the saved asset ID before retrying.') if passthrough == true && result['passthrough'] != true
192
195
  result['warning'] = response['warning'] if response['warning'].instance_of?(String)
193
196
  result
194
197
  end
@@ -484,7 +484,7 @@ module Kompressr
484
484
  Validation.bad unless status
485
485
  context.retry_after_ms = self.class.retry_after(head, parsed) if head
486
486
  context.check!
487
- if recover_upload_id && status.between?(200, 299) && parsed.instance_of?(Hash) && parsed['success'] == true && parsed['data'].instance_of?(Hash)
487
+ if recover_upload_id && parsed.instance_of?(Hash) && [true, false].include?(parsed['success']) && parsed['data'].instance_of?(Hash)
488
488
  candidate = parsed['data']['asset_id']
489
489
  context.asset_id = candidate.to_i if Validation.finite?(candidate) && candidate.positive? && candidate <= Validation::MAX_SAFE && candidate == candidate.to_i
490
490
  end
@@ -495,7 +495,7 @@ module Kompressr
495
495
  code = 'API_ERROR' unless code.instance_of?(String) && /\A[A-Z][A-Z0-9_]{0,99}\z/.match?(code) && !code.include?(@key)
496
496
  raise Error.new(safe_message(data['error'] || "Kompressr returned HTTP #{status}."), kind: 'api', code: code,
497
497
  status: status, retry_after_ms: context.retry_after_ms, asset_id: context.asset_id,
498
- may_have_succeeded: method != 'GET' && (status < 400 || status >= 500)), cause: nil
498
+ may_have_succeeded: method != 'GET' && (status < 400 || status >= 500 || (recover_upload_id && !context.asset_id.nil?))), cause: nil
499
499
  end
500
500
  result = parse.call(parsed)
501
501
  context.check!
@@ -155,6 +155,7 @@ module Kompressr
155
155
  result['original_size'] = nonnegative(v['original_size'])
156
156
  string(v['original_name']) if accepted
157
157
  string(v['asset_type'])
158
+ result['passthrough'] = boolean(v['passthrough']) if v.key?('passthrough')
158
159
  optional_strings(v, %w[original_name deletion_requested_at external_id created_at input_format output_format private_url_expires_at warning])
159
160
  urls(v)
160
161
  bad('Private asset response contains a public URL.') if v['visibility'] == 'private' && %w[cdn_url cdn_url_avif].any? { |name| v.key?(name) }
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Kompressr
4
- VERSION = '0.1.0'
4
+ VERSION = '0.2.0'
5
5
  end
metadata CHANGED
@@ -1,13 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: kompressr-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kompressr
8
+ autorequire:
8
9
  bindir: bin
9
10
  cert_chain: []
10
- date: 1980-01-02 00:00:00.000000000 Z
11
+ date: 2026-11-18 00:00:00.000000000 Z
11
12
  dependencies:
12
13
  - !ruby/object:Gem::Dependency
13
14
  name: json
@@ -131,6 +132,7 @@ dependencies:
131
132
  version: '1'
132
133
  description: Upload, wait for processing, sign private links and manage scoped identities
133
134
  using a framework-independent Ruby client.
135
+ email:
134
136
  executables: []
135
137
  extensions: []
136
138
  extra_rdoc_files: []
@@ -159,6 +161,7 @@ metadata:
159
161
  bug_tracker_uri: https://github.com/kompressrcdn/clients/issues
160
162
  allowed_push_host: https://rubygems.org
161
163
  rubygems_mfa_required: 'true'
164
+ post_install_message:
162
165
  rdoc_options: []
163
166
  require_paths:
164
167
  - lib
@@ -173,7 +176,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
173
176
  - !ruby/object:Gem::Version
174
177
  version: '0'
175
178
  requirements: []
176
- rubygems_version: 4.0.16
179
+ rubygems_version: 3.4.19
180
+ signing_key:
177
181
  specification_version: 4
178
182
  summary: Official Ruby SDK for Kompressr file and platform APIs.
179
183
  test_files: []