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.
@@ -5,57 +5,60 @@ module Nohead
5
5
  # Drafts: changes to a record's content that wait until they are merged
6
6
  # into it, now or at a set time, while the record keeps its current
7
7
  # content. A record has at most one. `draft` is a draft ID ("drf_..."),
8
- # `record` a record ID and `collection` a collection ID or slug.
8
+ # `record` a record ID and `collection` a collection ID or slug. Every
9
+ # method takes `rich_text:`, as records' do.
9
10
  class Drafts < Resource
10
11
  # Starts the record's draft: `data` over the record's values, or with
11
12
  # `from_revision`, over an earlier revision's. A second draft raises
12
13
  # ConflictError (detail code `draft_exists`, with its `draft_id`).
13
- def create(record, data: {}, from_revision: nil, idempotency_key: nil)
14
+ def create(record, data: {}, from_revision: nil, idempotency_key: nil, rich_text: nil)
14
15
  @client.request("drafts_create", path: { record_id: record },
15
16
  body: { data: data, from_revision: from_revision }.compact,
16
- idempotency_key: idempotency_key)
17
+ idempotency_key: idempotency_key, rich_text: rich_text)
17
18
  end
18
19
 
19
20
  # A collection's drafts, most recently changed first. One record's
20
21
  # draft is `records.drafts(record)`.
21
- def list(collection, sort: nil, limit: nil, cursor: nil)
22
+ def list(collection, sort: nil, limit: nil, cursor: nil, rich_text: nil)
22
23
  @client.paginate("drafts_list", path: { collection_id: collection },
23
- query: { sort: sort, limit: limit, cursor: cursor })
24
+ query: { sort: sort, limit: limit, cursor: cursor }, rich_text: rich_text)
24
25
  end
25
26
 
26
27
  # With `data` as the record reads after the merge, for previews.
27
- def get(draft, expand: nil)
28
- @client.request("drafts_get", path: { draft_id: draft }, query: { expand: expand })
28
+ def get(draft, expand: nil, rich_text: nil)
29
+ @client.request("drafts_get", path: { draft_id: draft }, query: { expand: expand }, rich_text: rich_text)
29
30
  end
30
31
 
31
32
  # Sets the given fields (nil clears one), as a record update does.
32
- def update(draft, data:, if_match: nil, idempotency_key: nil)
33
+ def update(draft, data:, if_match: nil, idempotency_key: nil, rich_text: nil)
33
34
  @client.request("drafts_update", path: { draft_id: draft }, body: { data: data },
34
- if_match: if_match, idempotency_key: idempotency_key)
35
+ if_match: if_match, idempotency_key: idempotency_key, rich_text: rich_text)
35
36
  end
36
37
 
37
38
  # Deletes the draft for good; returns it as it was.
38
- def discard(draft, if_match: nil, idempotency_key: nil)
39
+ def discard(draft, if_match: nil, idempotency_key: nil, rich_text: nil)
39
40
  @client.request("drafts_discard", path: { draft_id: draft }, if_match: if_match,
40
- idempotency_key: idempotency_key)
41
+ idempotency_key: idempotency_key, rich_text: rich_text)
41
42
  end
42
43
 
43
44
  # Applies the draft to its record now, as one `merge` revision, and
44
45
  # returns the record. Content only: the record stays live or not.
45
- def merge(draft, if_match: nil, idempotency_key: nil, change_note: nil)
46
+ def merge(draft, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
46
47
  @client.request("drafts_merge", path: { draft_id: draft }, if_match: if_match,
47
- idempotency_key: idempotency_key, change_note: change_note)
48
+ idempotency_key: idempotency_key, change_note: change_note,
49
+ rich_text: rich_text)
48
50
  end
49
51
 
50
52
  # Merges the draft at `merge_at` (a Time or ISO 8601 string in the
51
53
  # future); returns the draft.
52
- def schedule(draft, merge_at:, idempotency_key: nil)
54
+ def schedule(draft, merge_at:, idempotency_key: nil, rich_text: nil)
53
55
  @client.request("drafts_schedule", path: { draft_id: draft }, body: { merge_at: merge_at },
54
- idempotency_key: idempotency_key)
56
+ idempotency_key: idempotency_key, rich_text: rich_text)
55
57
  end
56
58
 
57
- def unschedule(draft, idempotency_key: nil)
58
- @client.request("drafts_unschedule", path: { draft_id: draft }, idempotency_key: idempotency_key)
59
+ def unschedule(draft, idempotency_key: nil, rich_text: nil)
60
+ @client.request("drafts_unschedule", path: { draft_id: draft }, idempotency_key: idempotency_key,
61
+ rich_text: rich_text)
59
62
  end
60
63
  end
61
64
  end
@@ -14,8 +14,7 @@ module Nohead
14
14
  # `sort` is "-created_at" (the default) or "created_at".
15
15
  def list(filter: nil, sort: nil, limit: nil, cursor: nil)
16
16
  filter = filter&.transform_keys(&:to_sym)
17
- types = filter&.[](:resource_type)
18
- filter = filter.merge(resource_type: { in: types }) if types.is_a?(Array)
17
+ filter[:resource_type] = one_or_in(filter[:resource_type]) if filter&.key?(:resource_type)
19
18
  @client.paginate("audit_events_list",
20
19
  query: { filter: filter, sort: sort, limit: limit, cursor: cursor })
21
20
  end
@@ -4,8 +4,8 @@ module Nohead
4
4
  module Resources
5
5
  # The base of the resources: each holds the client it sends requests with.
6
6
  class Resource
7
- # Request options that are headers, not body fields.
8
- OPTIONS = %i[change_note if_match].freeze
7
+ # Request options, not body fields.
8
+ OPTIONS = %i[change_note if_match rich_text].freeze
9
9
 
10
10
  def initialize(client)
11
11
  @client = client
@@ -17,14 +17,22 @@ module Nohead
17
17
 
18
18
  # The keyword arguments a method sends as the body. SDK options would
19
19
  # land there when the method doesn't take them (its operation doesn't
20
- # declare the header), so they raise ArgumentError as Ruby does for
21
- # unknown keywords.
20
+ # declare the header or query parameter), so they raise ArgumentError as
21
+ # Ruby does for unknown keywords.
22
22
  def body_of(params)
23
23
  option = OPTIONS.find { |name| params.key?(name) }
24
24
  raise ArgumentError, "unknown keyword: :#{option}" if option
25
25
 
26
26
  params
27
27
  end
28
+
29
+ # One value as it is, several as `{ in: [...] }`; an empty list (like an
30
+ # asset field's accepted_types) is no filter.
31
+ def one_or_in(value)
32
+ return value unless value.is_a?(Array)
33
+
34
+ value.empty? ? nil : { in: value }
35
+ end
28
36
  end
29
37
 
30
38
  # Records: the content of a collection. `collection` is a collection ID or
@@ -40,56 +48,62 @@ module Nohead
40
48
  # A collection's records, newest first by default. `filter` holds
41
49
  # filters ({ published_at: { exists: true } } for published records),
42
50
  # `expand` relation or asset fields to embed under `expanded` (at most 5).
43
- def list(collection, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil)
51
+ # Methods that return records or drafts take `rich_text:` ("document",
52
+ # "html" or "markdown"): how their rich text fields read.
53
+ def list(collection, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil, rich_text: nil)
44
54
  @client.paginate("records_list", path: { collection_id: collection }, query: {
45
55
  filter: filter, sort: sort, expand: expand, limit: limit, cursor: cursor
46
- })
56
+ }, rich_text: rich_text)
47
57
  end
48
58
 
49
59
  # A deleted record too, with `deleted_at` and `purge_after`.
50
- def get(record, expand: nil)
51
- @client.request("records_get", path: { record_id: record }, query: { expand: expand })
60
+ def get(record, expand: nil, rich_text: nil)
61
+ @client.request("records_get", path: { record_id: record }, query: { expand: expand }, rich_text: rich_text)
52
62
  end
53
63
 
54
64
  # Creates an unpublished record: create("posts", data: { title: "Hello" }).
55
65
  # With upsert_on:, the key of a unique field, it updates the record holding
56
66
  # that value instead, if one exists, so a sync can run again without
57
67
  # duplicates; if_match: then applies to that update.
58
- def create(collection, if_match: nil, idempotency_key: nil, change_note: nil, **params)
68
+ def create(collection, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil, **params)
59
69
  @client.request("records_create", path: { collection_id: collection }, body: body_of(params),
60
70
  if_match: if_match, idempotency_key: idempotency_key,
61
- change_note: change_note)
71
+ change_note: change_note, rich_text: rich_text)
62
72
  end
63
73
 
64
74
  # Sets the given fields (nil clears one); others keep their values.
65
- def update(record, if_match: nil, idempotency_key: nil, change_note: nil, **params)
75
+ def update(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil, **params)
66
76
  @client.request("records_update", path: { record_id: record }, body: body_of(params),
67
77
  if_match: if_match, idempotency_key: idempotency_key,
68
- change_note: change_note)
78
+ change_note: change_note, rich_text: rich_text)
69
79
  end
70
80
 
71
81
  # Soft-deletes the record: restore brings it back until its `purge_after`.
72
82
  # Deleting a deleted record changes nothing.
73
- def delete(record, if_match: nil, idempotency_key: nil, change_note: nil)
83
+ def delete(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
74
84
  @client.request("records_delete", path: { record_id: record }, if_match: if_match,
75
- idempotency_key: idempotency_key, change_note: change_note)
85
+ idempotency_key: idempotency_key, change_note: change_note,
86
+ rich_text: rich_text)
76
87
  end
77
88
 
78
- def restore(record, if_match: nil, idempotency_key: nil, change_note: nil)
89
+ def restore(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
79
90
  @client.request("records_restore", path: { record_id: record }, if_match: if_match,
80
- idempotency_key: idempotency_key, change_note: change_note)
91
+ idempotency_key: idempotency_key, change_note: change_note,
92
+ rich_text: rich_text)
81
93
  end
82
94
 
83
95
  # A live record with a pending draft raises ConflictError (detail code
84
96
  # `draft_pending`): publishing never merges a draft (drafts.merge does).
85
- def publish(record, if_match: nil, idempotency_key: nil, change_note: nil)
97
+ def publish(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
86
98
  @client.request("records_publish", path: { record_id: record }, if_match: if_match,
87
- idempotency_key: idempotency_key, change_note: change_note)
99
+ idempotency_key: idempotency_key, change_note: change_note,
100
+ rich_text: rich_text)
88
101
  end
89
102
 
90
- def unpublish(record, if_match: nil, idempotency_key: nil, change_note: nil)
103
+ def unpublish(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
91
104
  @client.request("records_unpublish", path: { record_id: record }, if_match: if_match,
92
- idempotency_key: idempotency_key, change_note: change_note)
105
+ idempotency_key: idempotency_key, change_note: change_note,
106
+ rich_text: rich_text)
93
107
  end
94
108
 
95
109
  # What is live: since when, by whom, and the revision. Raises
@@ -122,8 +136,9 @@ module Nohead
122
136
  end
123
137
 
124
138
  # The record's drafts: at most one for now.
125
- def drafts(record, limit: nil, cursor: nil)
126
- @client.paginate("record_drafts_list", path: { record_id: record }, query: { limit: limit, cursor: cursor })
139
+ def drafts(record, limit: nil, cursor: nil, rich_text: nil)
140
+ @client.paginate("record_drafts_list", path: { record_id: record }, query: { limit: limit, cursor: cursor },
141
+ rich_text: rich_text)
127
142
  end
128
143
 
129
144
  # A collection's pending scheduled changes, soonest first: publishes,
@@ -141,9 +156,10 @@ module Nohead
141
156
 
142
157
  # Publishes, unpublishes, deletes, restores or updates up to 100 records.
143
158
  # Each record succeeds or fails on its own; see `results`.
144
- def bulk(collection, idempotency_key: nil, change_note: nil, **params)
159
+ def bulk(collection, idempotency_key: nil, change_note: nil, rich_text: nil, **params)
145
160
  @client.request("records_bulk", path: { collection_id: collection }, body: body_of(params),
146
- idempotency_key: idempotency_key, change_note: change_note)
161
+ idempotency_key: idempotency_key, change_note: change_note,
162
+ rich_text: rich_text)
147
163
  end
148
164
 
149
165
  # The changes between two revisions: diff(record, from: 1, to: 2).
@@ -153,11 +169,11 @@ module Nohead
153
169
 
154
170
  # Full-text search in one collection, matching its searchable fields, most
155
171
  # relevant first, through the first 1,000 hits.
156
- def search(collection, query, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil)
172
+ def search(collection, query, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil, rich_text: nil)
157
173
  @client.paginate("collections_search", path: { collection_id: collection }, query: {
158
174
  q: query, filter: filter, sort: sort, expand: expand, limit: limit,
159
175
  cursor: cursor
160
- })
176
+ }, rich_text: rich_text)
161
177
  end
162
178
  end
163
179
 
@@ -176,10 +192,12 @@ module Nohead
176
192
 
177
193
  # Restores the record's data as of `revision`, as a new revision. With
178
194
  # dry_run: true, previews it.
179
- def revert(record, revision, dry_run: false, if_match: nil, idempotency_key: nil, change_note: nil)
195
+ def revert(record, revision, dry_run: false, if_match: nil, idempotency_key: nil, change_note: nil,
196
+ rich_text: nil)
180
197
  @client.request("record_revisions_revert", path: { record_id: record, revision: revision },
181
198
  query: { dry_run: dry_run || nil }, if_match: if_match,
182
- idempotency_key: idempotency_key, change_note: change_note)
199
+ idempotency_key: idempotency_key, change_note: change_note,
200
+ rich_text: rich_text)
183
201
  end
184
202
  end
185
203
 
@@ -3,6 +3,7 @@
3
3
  require "net/http"
4
4
  require "openssl"
5
5
  require "uri"
6
+ require "zlib"
6
7
 
7
8
  module Nohead
8
9
  # A response: status, headers (lowercase names) and body text.
@@ -20,15 +21,23 @@ module Nohead
20
21
  elsif body
21
22
  request.body = body
22
23
  end
23
- http = Net::HTTP.new(uri.host, uri.port)
24
- http.use_ssl = uri.scheme == "https"
25
- http.open_timeout = http.read_timeout = http.write_timeout = timeout
26
- response = http.start { http.request(request) }
24
+ # The proxy comes from the environment (http_proxy, no_proxy), as Net::HTTP.new.
25
+ # No retries of its own (it retries a GET, PUT or DELETE that times out
26
+ # or loses its connection once, and a PUT with the stream already
27
+ # read): the client retries, and knows when it can.
28
+ response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout,
29
+ read_timeout: timeout, write_timeout: timeout,
30
+ max_retries: 0) do |http|
31
+ http.request(request)
32
+ end
27
33
  Response.new(response.code.to_i, response.each_header.to_h, response.body.to_s)
28
34
  rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
29
35
  raise TimeoutError, "The request to #{uri.host} timed out after #{timeout} s"
30
36
  rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
31
37
  raise ConnectionError, "Could not reach #{uri.host}: #{e.message}"
38
+ # A broken status line, header or compressed body: retried like a dropped connection.
39
+ rescue Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError, Zlib::Error => e
40
+ raise ConnectionError, "The response from #{uri.host} could not be read: #{e.message}"
32
41
  end
33
42
  end
34
43
  end
@@ -19,16 +19,18 @@ module Nohead
19
19
 
20
20
  def initialize(file, filename: nil, content_type: nil, byte_size: nil)
21
21
  name, size = file.is_a?(String) || file.is_a?(Pathname) ? open_path(Pathname(file)) : open_io(file)
22
- @filename = filename || name || "upload"
22
+ # An empty filename or content type is the same as none.
23
+ @filename = present(filename) || present(name) || "upload"
23
24
  @byte_size = byte_size || size or
24
25
  raise UploadError, "Uploading a stream that cannot seek needs byte_size:"
25
- @content_type = content_type ||
26
+ @content_type = present(content_type) ||
26
27
  CONTENT_TYPES.fetch(File.extname(@filename).downcase, "application/octet-stream")
27
- @start = @io.respond_to?(:pos) ? @io.pos : 0
28
+ @start = position(@io)
28
29
  end
29
30
 
30
- # Whether the bytes can be sent again (for retries).
31
- def replayable? = @io.respond_to?(:rewind) && @io.respond_to?(:pos)
31
+ # Whether the bytes can be sent again (for retries): a pipe or socket
32
+ # can't seek back to where they start.
33
+ def replayable? = !@start.nil? && @io.respond_to?(:pos=)
32
34
 
33
35
  def rewind
34
36
  @io.pos = @start if replayable?
@@ -40,6 +42,10 @@ module Nohead
40
42
 
41
43
  private
42
44
 
45
+ def present(value)
46
+ value unless value.to_s.empty?
47
+ end
48
+
43
49
  def open_path(path)
44
50
  @io = path.open("rb")
45
51
  @owned = true
@@ -54,6 +60,12 @@ module Nohead
54
60
  [name, remaining(io)]
55
61
  end
56
62
 
63
+ def position(io)
64
+ io.pos if io.respond_to?(:pos)
65
+ rescue IOError, SystemCallError
66
+ nil
67
+ end
68
+
57
69
  def remaining(io)
58
70
  return io.size - io.pos if io.respond_to?(:size) && io.respond_to?(:pos)
59
71
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Nohead
4
- VERSION = "0.8.0"
4
+ VERSION = "0.10.0"
5
5
  end
@@ -31,8 +31,8 @@ module Nohead
31
31
  raise WebhookVerificationError, "The webhook timestamp is too far from the current time"
32
32
  end
33
33
 
34
- key = secret.delete_prefix("whsec_").unpack1("m0")
35
- expected = [OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{body}")].pack("m0")
34
+ # The body as bytes too, so a non-ASCII id and body in different encodings combine.
35
+ expected = [OpenSSL::HMAC.digest("SHA256", key(secret), "#{id}.#{timestamp}.#{body.to_s.b}")].pack("m0")
36
36
  matched = signatures.split.any? do |entry|
37
37
  version, signature = entry.split(",", 2)
38
38
  version == "v1" && signature && OpenSSL.secure_compare(signature, expected)
@@ -40,16 +40,32 @@ module Nohead
40
40
  raise WebhookVerificationError, "No webhook signature matches" unless matched
41
41
 
42
42
  NoheadObject.wrap(JSON.parse(body))
43
- rescue ArgumentError
44
- raise WebhookVerificationError, "The webhook secret is not base64"
45
43
  rescue JSON::ParserError
46
44
  raise WebhookVerificationError, "The webhook body is not JSON"
47
45
  end
48
46
 
49
- def self.header(headers, name)
50
- return headers[name] || headers[name.split("-").map(&:capitalize).join("-")] unless headers.is_a?(Hash)
47
+ def self.key(secret)
48
+ key = secret.to_s.b.delete_prefix("whsec_").unpack1("m0")
49
+ # Unset (nil) or empty, as from a missing environment variable.
50
+ raise WebhookVerificationError, "The webhook secret is empty" if key.empty?
51
+
52
+ key
53
+ rescue ArgumentError
54
+ raise WebhookVerificationError, "The webhook secret is not base64"
55
+ end
56
+ private_class_method :key
51
57
 
52
- headers.find { |key, _| key.to_s.downcase == name }&.last
58
+ # As bytes: headers come in any encoding, and not always valid, which
59
+ # must not raise ArgumentError or Encoding::CompatibilityError.
60
+ def self.header(headers, name)
61
+ value = if headers.is_a?(Hash)
62
+ headers.find { |key, _| key.to_s.downcase == name }&.last
63
+ else
64
+ headers[name] || headers[name.split("-").map(&:capitalize).join("-")]
65
+ end
66
+ # A repeated header, as some frameworks give it: its values, space-separated.
67
+ value = value.join(" ") if value.is_a?(Array)
68
+ value&.b
53
69
  end
54
70
  private_class_method :header
55
71
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: nohead
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.8.0
4
+ version: 0.10.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Nohead