nohead 0.8.0 → 0.10.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: aaf4c7fc6c9f1c9783210f08d5d42cd01aa7ae30e3b30f3398c5bc5eb252c960
4
- data.tar.gz: afd201145f4734efbb695c717b8073c5f100fac11fdec822467dc4345ea7a1de
3
+ metadata.gz: 614f02b14cf5307614caf01ae06d458d770bff423c34d567d0fe8f7924467298
4
+ data.tar.gz: 052d1089ecc31f984b4d1e143638b4b26b8d393c1a8eac9764a5e6df8a76d364
5
5
  SHA512:
6
- metadata.gz: ff59ead7b5f84026e63d42fd7751c272b7eff489fad447f0bd397f00d21ab57cb475fd989c0bca218efdcc5abcfdf44e681a91a2a0c0c61252b508d08a6e09c4
7
- data.tar.gz: 21afb854940c2fdda4181b0c8a03e9accd46127e16fe2f7455f17f0fb0e6ab1b8f7033ac414cee25917c599d59d832ae6f7e185759f8571b15588ebc5d9a300c
6
+ metadata.gz: 432a87faa068fb1719a38ba559520de892c0cf48abc0783b1ba1c0114d6fbe252b5cffd72c0d89d40de323c563e7c528334796ff7da0695ff2b48b2636fa46da
7
+ data.tar.gz: 1383b012a30ec74972234dcda1c61f62f75e948929c9f8c6d14e52fcd7245595521c2e00426b0e0030a4b3887dc77231c2808ec5ef0390aa8818b8f655216c2e
data/CHANGELOG.md CHANGED
@@ -5,6 +5,105 @@ Changes to the `nohead` gem that you can notice. Versions follow
5
5
  releases; a change that could break your code is a major one. Each release's
6
6
  section is its GitHub release's notes.
7
7
 
8
+ ## 0.10.0
9
+
10
+ - Rich text fields read as HTML or Markdown with `rich_text:` (`"document"`,
11
+ the default, `"html"` or `"markdown"`), on `Nohead::Client.new` and
12
+ `with_options` for every call, or on a call: the methods that return
13
+ records or drafts take it, and a call's value wins over the client's. The
14
+ field's value is then a string, in records embedded with `expand:` too.
15
+ Writing Markdown already worked: `data` is sent as it is.
16
+
17
+ ## 0.9.0
18
+
19
+ - **Breaking:** the client no longer reads `NOHEAD_API_URL`: a stray value
20
+ sent requests, with the API key, to another host. The base URL is
21
+ `base_url:`, else `https://api.nohead.io`; pass `base_url:` to use another
22
+ API, as in `Nohead::Client.new(base_url: ENV.fetch("NOHEAD_API_URL"))`.
23
+ - A request is sent once per attempt. Net::HTTP retried a GET, PUT or DELETE
24
+ that timed out or lost its connection once more on its own, so a stalled
25
+ request waited twice the `timeout:`, `max_retries:` sent more attempts than
26
+ asked (unseen by `on_retry:`), and a stalled upload was sent again with its
27
+ stream already read.
28
+ - `Images.url` writes the same URL as the other SDKs for the same image and
29
+ options: a whole-number Float is written as an integer (`dpr: 2.0` is
30
+ `dpr:2`, not `dpr:2.0`), and `dpr: 0` or `quality: 0` is left out rather
31
+ than written as `dpr:0` or `q:0`.
32
+ - Deprecation and plan-usage warnings are given once per process, as in the
33
+ other SDKs, rather than once per client: an app that builds a client per
34
+ request no longer repeats them on every request.
35
+ - `assets.upload` of a stream that cannot seek, such as a pipe or `$stdin`,
36
+ with `byte_size:` no longer raises `Errno::ESPIPE`. Its bytes are sent
37
+ once: a storage error is not retried, since they can't be read again.
38
+ - `Webhooks.unwrap` reads headers, body and secret as bytes. A non-ASCII
39
+ `webhook-id` with a binary body (as Rack passes it) no longer raises
40
+ `Encoding::CompatibilityError`, a secret in another encoding raises
41
+ `WebhookVerificationError`, and a header that is not valid UTF-8 is refused
42
+ for its signature or timestamp, not as "The webhook secret is not base64".
43
+ - `Webhooks.unwrap` refuses an unset or empty secret with
44
+ `WebhookVerificationError` ("The webhook secret is empty"), instead of
45
+ `NoMethodError` or a signature mismatch, and verifies a repeated
46
+ `webhook-signature` header given as an Array.
47
+ - A path value of `"."` or `".."` (an ID such as `records.get(".")`) raises
48
+ `Nohead::Error` (`Invalid record_id: "."`) before anything is sent, as
49
+ `nil` or `""` does, instead of reaching a URL that a proxy could resolve to
50
+ another path.
51
+ - An empty string is the same as leaving an option out, as in the other
52
+ SDKs: `project_id: ""` looks the project up, `idempotency_key: ""`
53
+ generates a key (it was sent empty) and `change_note: ""` sends no
54
+ `Nohead-Change-Note` header.
55
+ - `base_url:` loses every trailing slash (it lost one), and a base URL that
56
+ isn't `http` or `https` raises `Nohead::Error` ("base_url must be an http or
57
+ https URL") when the client is built, instead of `NoMethodError` at the
58
+ first request.
59
+ - Headers are sent once per name, whatever its case: the client's
60
+ `headers:` replace the SDK's own, and the ones request options set
61
+ (`Content-Type`, `Idempotency-Key`, `If-Match`, `Nohead-Change-Note`)
62
+ replace both. A custom `transport:` used to get both spellings.
63
+ - `if_match:` takes a Hash with a revision (`{ revision: 3 }`) as well as a
64
+ revision number or a record or draft; anything else, such as `"3"`, raises
65
+ `ArgumentError` (a Hash or String was sent as it was written).
66
+ - The project lookup (`GET /v1/me`, without `project_id:`) runs once when
67
+ several threads need it at the same time.
68
+ - `search` with both `collections:` and a `collection` filter searches
69
+ `collections:`, as the other SDKs do (the filter won).
70
+ - `APIError#api_message` is the API's own message, without the status, type
71
+ and request ID that `message` adds.
72
+ - A redirect is an `APIError` whose message says to check the base URL
73
+ (`301 redirect: The API answered with a redirect to <Location>; check the
74
+ base URL`), instead of "Request failed with status 301".
75
+ - A malformed response (a broken status line or header,
76
+ `Net::HTTPBadResponse`, `Net::HTTPHeaderSyntaxError`, `Net::ProtocolError`,
77
+ or a broken compressed body) is a `ConnectionError`, retried like a
78
+ dropped connection, instead of escaping as Net::HTTP's own error.
79
+ - A list call whose response isn't a page raises `Nohead::Error` ("The API's
80
+ response could not be read (HTTP 200)") instead of `KeyError` or
81
+ `NoMethodError`.
82
+ - `Retry-After` is read with spaces around it (`" 5"`); anything but whole or
83
+ decimal seconds or an HTTP date is ignored, as before.
84
+ - Error details that aren't objects are kept, with the code `"unknown"` and
85
+ the value as their message, instead of left out.
86
+ - An empty `Deprecation` header no longer warns.
87
+ - `on_retry:`, a client option, is called before each retry's wait (of
88
+ uploads' bytes too) with a `Nohead::RetryEvent`: the attempt, the delay in
89
+ seconds, the URL, and the status or error that failed, as the other SDKs'
90
+ retry callbacks are.
91
+ - `with_options(timeout:, max_retries:, headers:, on_retry:)` returns a copy
92
+ of the client with other settings, sharing its project lookup.
93
+ - `timeout:` is documented as what it is: the longest wait without progress
94
+ (connecting, waiting for the response, between reads and writes of a
95
+ body), not a limit on the whole attempt.
96
+ - `assets.upload` raises `UploadError` ("Could not upload a.png: <reason>",
97
+ with the `ConnectionError` as its `cause`) when storage can't be reached
98
+ or times out, as it does when storage refuses the bytes, instead of
99
+ `ConnectionError` or `TimeoutError`.
100
+ - `assets.upload` with `filename: ""` or `content_type: ""` uses the
101
+ defaults (the file's name, else `upload`; the extension's type, else
102
+ `application/octet-stream`) instead of sending them empty.
103
+ - `Images.url` leaves out options given as `""` (`gravity: ""`,
104
+ `format: ""`...) instead of writing `g:` or a trailing `@`, and `fit: nil`
105
+ (or `""`) means the default `contain` instead of raising `ArgumentError`.
106
+
8
107
  ## 0.8.0
9
108
 
10
109
  - Assets have `file_url`, the file as uploaded, which downloads under its
data/README.md CHANGED
@@ -20,6 +20,7 @@ end
20
20
  - [Configuration](#configuration)
21
21
  - [Records](#records)
22
22
  - [Drafts](#drafts)
23
+ - [Rich text](#rich-text)
23
24
  - [Pagination](#pagination)
24
25
  - [Errors](#errors)
25
26
  - [Retries and idempotency](#retries-and-idempotency)
@@ -41,24 +42,37 @@ gem "nohead"
41
42
 
42
43
  It needs Ruby 3.3 or newer. It uses only Ruby's standard library (Net::HTTP, JSON, OpenSSL). Use it on servers: API keys are secrets.
43
44
 
45
+ Until 1.0, any release may break your code: pin a version, and read the changelog's **Breaking** entries before upgrading.
46
+
44
47
  ## Configuration
45
48
 
46
49
  ```ruby
47
50
  nohead = Nohead::Client.new(
48
- api_key: ENV.fetch("NOHEAD_API_KEY"), # default: NOHEAD_API_KEY
49
- base_url: "https://api.nohead.io" # default: NOHEAD_API_URL, else production
51
+ api_key: ENV.fetch("NOHEAD_API_KEY"), # the default
52
+ timeout: 10,
53
+ max_retries: 3
50
54
  )
51
55
  ```
52
56
 
53
57
  | Option | Default | |
54
58
  |---|---|---|
55
59
  | `api_key:` | `NOHEAD_API_KEY` | A project API key (`nohead_sk_...`, or `nohead_pk_...` when published-only). Required. |
56
- | `base_url:` | `NOHEAD_API_URL`, else `https://api.nohead.io` | |
60
+ | `base_url:` | `https://api.nohead.io` | For a proxy, or a mock server in tests. |
57
61
  | `project_id:` | the key's project | Looked up once with `GET /v1/me` when omitted. |
58
62
  | `max_retries:` | `2` | See [retries](#retries-and-idempotency). |
59
- | `timeout:` | `60` | Seconds per attempt. |
63
+ | `timeout:` | `60` | The longest wait in seconds without progress, per attempt: connecting, waiting for the response, and between reads and writes of a body. A response that keeps arriving doesn't time out. |
60
64
  | `headers:` | `{}` | Added to every request. |
61
65
  | `warnings:` | `true` | Warns about deprecated operations and plan usage, once each. |
66
+ | `on_retry:` | | Called before each retry's wait. See [retries](#retries-and-idempotency). |
67
+ | `rich_text:` | `"document"` | How rich text fields read: see [rich text](#rich-text). |
68
+
69
+ An empty string is the same as leaving an option out (`api_key: ""` reads `NOHEAD_API_KEY`, `base_url: ""` uses `https://api.nohead.io`). The base URL comes only from `base_url:`, never from the environment. A `base_url:` that isn't `http` or `https` raises `Nohead::Error`.
70
+
71
+ `with_options` gives a copy of the client with other settings (`timeout:`, `max_retries:`, `headers:`, added to the client's, `on_retry:` and `rich_text:`), sharing its project lookup:
72
+
73
+ ```ruby
74
+ nohead.with_options(timeout: 5, max_retries: 0).records.get(id)
75
+ ```
62
76
 
63
77
  API keys belong to a project, so methods like `collections.list` need no project ID. Collections can be named by ID or slug everywhere.
64
78
 
@@ -101,6 +115,24 @@ nohead.drafts.merge(draft.id) # or drafts.schedule(draft.id, merge_at: ...)
101
115
  - `records.drafts(id)` lists a record's draft, and `drafts.list(collection)` a collection's.
102
116
  - `drafts.discard` deletes one for good.
103
117
 
118
+ ## Rich text
119
+
120
+ A rich text field is written as Markdown or as a document (ProseMirror JSON), and reads as a document unless you ask for HTML or Markdown with `rich_text:`, for the whole client or for one call:
121
+
122
+ ```ruby
123
+ nohead.records.create("posts", data: { body: "## Hello\n\nWritten in **Markdown**." })
124
+
125
+ nohead = Nohead::Client.new(rich_text: "html")
126
+ nohead.records.get(id).data["body"] # an HTML string
127
+ nohead.records.get(id, rich_text: "markdown").data["body"] # a Markdown string
128
+ ```
129
+
130
+ - With `"html"` or `"markdown"`, the field's value is a string instead of the document, in records embedded with `expand:` too. `"document"` is the default.
131
+ - The methods that return records or drafts take `rich_text:`; a call's value wins over the client's, and other methods never send it.
132
+ - HTML has every text and attribute escaped, ready to put in a page. Images come with their URLs, so they need no `expand:`.
133
+ - Record history (`records.revisions.list` and `get`) and webhook events keep documents.
134
+ - A string you write is read as Markdown, so write back Markdown or the document, never the HTML: with `rich_text: "html"` on the client, writes answer with HTML too.
135
+
104
136
  ## Pagination
105
137
 
106
138
  List methods return the first page, a `Nohead::Page`. It's Enumerable: `each`, `map`, `first` and so on walk every item across pages, fetching the next page only when needed.
@@ -132,7 +164,7 @@ nohead.records.list("products", filter: { price: { lt: 50 }, category: { in: %w[
132
164
 
133
165
  ## Errors
134
166
 
135
- Every error is a `Nohead::Error`. API errors are `Nohead::APIError`s with `status`, `type`, `message`, `request_id`, `details` and `headers`, in a class per type:
167
+ Every error is a `Nohead::Error`. API errors are `Nohead::APIError`s with `status`, `type`, `message`, `api_message` (the API's own message, without the status, type and request ID), `request_id`, `details` and `headers`, in a class per type:
136
168
 
137
169
  | Class | Status |
138
170
  |---|---|
@@ -148,6 +180,8 @@ Every error is a `Nohead::Error`. API errors are `Nohead::APIError`s with `statu
148
180
  | `InternalServerError` | 500 and other 5xx |
149
181
  | `ServiceUnavailableError` | 503 |
150
182
 
183
+ A redirect is an `APIError` too ("301 redirect: The API answered with a redirect to …; check the base URL"): the SDK doesn't follow redirects.
184
+
151
185
  Other errors:
152
186
 
153
187
  - `Nohead::ConnectionError`, and `Nohead::TimeoutError`, which is a kind of `ConnectionError`
@@ -167,7 +201,13 @@ end
167
201
  Failed requests are retried twice by default (`max_retries:`), with exponential backoff:
168
202
 
169
203
  - what's retried: connection errors, timeouts, 429, 500, 502, 503, 504, and a 409 for a request that is still running
170
- - `Retry-After` is honored up to 60 seconds; a longer one raises `RateLimitError` straight away
204
+ - `Retry-After` (seconds, or an HTTP date) is honored up to 60 seconds; a longer one raises `RateLimitError` straight away
205
+
206
+ `on_retry:` hears of each retry before its wait, uploads' too, as a `Nohead::RetryEvent` (`attempt`, from 1; `delay`, in seconds; `url`; `status`, nil when the connection failed; and `error`):
207
+
208
+ ```ruby
209
+ nohead = Nohead::Client.new(on_retry: ->(event) { logger.warn("Retry #{event.attempt} of #{event.url} in #{event.delay} s") })
210
+ ```
171
211
 
172
212
  Every write gets an `Idempotency-Key` that stays the same across its retries, so a retry after a lost response never writes twice. To make a write safe across your own retries (a job that may run twice), pass a key:
173
213
 
@@ -190,14 +230,13 @@ rescue Nohead::PreconditionFailedError => e
190
230
  end
191
231
  ```
192
232
 
193
- `if_match:` takes a record (or draft) or a revision number, on `records.update`, `delete`, `restore`, `publish`, `unpublish` and `revisions.revert`, and on `drafts.update`, `discard` and `merge`.
233
+ `if_match:` takes a record (or draft), a revision number or `{ revision: 3 }`, on `records.update`, `delete`, `restore`, `publish`, `unpublish` and `revisions.revert`, and on `drafts.update`, `discard` and `merge`.
194
234
 
195
235
  ## Assets
196
236
 
197
237
  ```ruby
198
238
  asset = nohead.assets.upload("cover.jpg")
199
239
  nohead.records.update(id, data: { cover: asset.id })
200
-
201
240
  ```
202
241
 
203
242
  **Images.** Image URLs are open: an image's `image_url` serves the whole image, and any of [imgproxy's processing options](https://docs.imgproxy.net/usage/processing) written into it transform it. `Nohead::Images.url` builds them without a request:
@@ -217,18 +256,18 @@ Thumbnails: an image's `preview_url` fits in 640×640, as WebP.
217
256
  2. Streams the bytes straight to storage.
218
257
  3. Completes the upload, which checks the file, and returns the `ready` asset.
219
258
 
220
- **Errors:** `UploadError` if storage refuses the bytes; `ValidationError` if the file fails the checks.
259
+ **Errors:** `UploadError` if the bytes don't reach storage: refused (`Storage refused the upload of cover.jpg (403)`, with its `status`), or unreachable or timed out (`Could not upload cover.jpg: …`, with the `ConnectionError` as its `cause`). `ValidationError` if the file fails the checks.
221
260
 
222
261
  **Resuming:** with an `idempotency_key:`, running the same upload again resumes it: the key starts the upload, and an asset that is already `ready` comes back without sending the bytes again. Once the upload's URL has expired (its `upload.expires_at`), it raises `UploadError`: start over with a new key.
223
262
 
224
- **Uploading from a browser:** create the upload on your server with `create_upload`, `PUT` the file from the browser, then `complete` it.
225
-
226
263
  **Renaming and alt text:** `update` changes an asset's `filename:` and `alt:` text, the default wherever the asset is used (`expand:` returns it with the asset). The file itself never changes.
227
264
 
228
265
  ```ruby
229
266
  nohead.assets.update(asset.id, alt: "The spring menu, on a chalkboard")
230
267
  ```
231
268
 
269
+ **Deleting:** `usage` shows which records use an asset. `delete` keeps the file until its `purge_after`, during which `restore` undoes it; `purge` removes a deleted asset for good, now.
270
+
232
271
  ## Search
233
272
 
234
273
  ```ruby
@@ -320,20 +359,32 @@ bundle exec rake generate # after updating openapi.json
320
359
  bundle exec rake samples # after changing test/calls.rb (the docs' code samples)
321
360
  ```
322
361
 
362
+ Before pushing, run what CI runs: the tests, RuboCop, and a check that the generated files are up to date:
363
+
364
+ ```bash
365
+ bundle exec rake test
366
+ bundle exec rubocop
367
+ bundle exec rake generate samples && git diff --exit-code # with your changes committed: a diff is a stale file
368
+ gem build nohead.gemspec
369
+ ```
370
+
323
371
  **How the code is organized:**
324
372
 
325
373
  - `openapi.json` is the API's published contract. `rake generate` derives the operation table, `lib/nohead/operations.rb`, from it.
326
374
  - The methods are written by hand.
327
375
  - `test/contract_test.rb` runs every call in `test/calls.rb`. It fails when an API-key operation in the contract has no method, when a query parameter is never sent (no method takes it, or no call passes it), or when a request doesn't match its operation (method, path, query parameters and JSON body, against their schemas). Each call gets an example of its operation's response, built from the contract's schema, and must return it.
376
+ - The unit tests answer with `test/fake_transport.rb`, which checks every request to the API and every reply against `openapi.json`, so a fixture can't drift from the API. Wrap a reply that breaks the contract on purpose (a gateway's HTML page, an unknown error type) in `raw(...)`.
377
+ - `test/network_test.rb` runs the real transport (Net::HTTP) against an HTTP server on 127.0.0.1, `test/local_server.rb`, for what goes over the wire: lengths, timeouts, redirects and broken replies.
378
+ - A test that makes no assertions fails.
328
379
 
329
- The smoke test (`smoke/smoke.rb`) runs the core flow against a real API, with the gem as installed from its built package. Nohead's own CI runs it on every API contract change.
380
+ The smoke test (`smoke/smoke.rb`) runs the core flow against a real API, with the gem as installed from its built package. The Nohead API repository runs it in its end-to-end tests and before every release.
330
381
 
331
382
  ## Releasing
332
383
 
333
- 1. Bump `lib/nohead/version.rb`.
384
+ 1. Bump `lib/nohead/version.rb`, then `bundle install` (`Gemfile.lock` records the version, and CI installs frozen).
334
385
  2. Add a section for the version to `CHANGELOG.md` (`## 1.2.3`), which becomes the release's notes.
335
386
  3. Merge to `main`. Its ruleset requires the **CI passed** check, so the commit goes through a pull request or a branch whose CI passed, and force pushes are refused.
336
- 4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`. Nobody else can push `v*` tags: a tag ruleset lets only that workflow's deploy key through.
387
+ 4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`. A tag ruleset lets only deploy keys push `v*` tags.
337
388
  5. The tag starts `.github/workflows/release.yml`. A build job checks the tag is on `main` and matches the version and its notes, and packs the gem, with no publishing credential. Its publishing job runs in the `release` environment, which only `v*` tags can use, and the registry's trusted publisher accepts only that environment. It pushes that gem to RubyGems through trusted publishing (no API key), then creates the GitHub release with the gem.
338
389
 
339
390
  ## License