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 +4 -4
- data/API.md +13 -1
- data/CHANGELOG.md +5 -0
- data/README.md +14 -2
- data/lib/kompressr/client.rb +5 -2
- data/lib/kompressr/transport.rb +2 -2
- data/lib/kompressr/validation.rb +1 -0
- data/lib/kompressr/version.rb +1 -1
- metadata +7 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9ba0796199657541189514cbb17e425a42b52179c50cd4a342a500040a416a03
|
|
4
|
+
data.tar.gz: a74a59cc64cfe7d40a93971572d404e96441862e95eed8d3836a8a0f17617a8d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
data/lib/kompressr/client.rb
CHANGED
|
@@ -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(
|
|
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
|
data/lib/kompressr/transport.rb
CHANGED
|
@@ -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 &&
|
|
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!
|
data/lib/kompressr/validation.rb
CHANGED
|
@@ -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) }
|
data/lib/kompressr/version.rb
CHANGED
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.
|
|
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:
|
|
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.
|
|
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: []
|