k9o 1.2.0-aarch64-linux → 1.5.2-aarch64-linux

data/lib/k9o/functions.rb

@@ -2,22 +2,56 @@
 
 module K9o
   # Function lifecycle namespace — k9o.functions.*.
+  #
+  # Upload the function's bytes first (+upload_artifact+ returns the +artifactKey+), then +deploy+ references that
+  # artifact. Deploy requires PROJECT_ADMIN and returns with status +deploying+; the function is ready when status
+  # flips to +active+.
   class Functions
+    ARTIFACT_CONTENT_TYPES = { 'wasm' => 'application/wasm', 'tar' => 'application/x-tar' }.freeze
+
+    attr_reader :triggers
+
     def initialize(config)
       @config = config
+      @triggers = FunctionTriggers.new(config)
     end
 
-    def deploy(name:, runtime:, code:, tier: nil, config: nil)
+    # POST /@<slug>/functions/artifacts with the raw bytes: a WebAssembly module for the gateway tier (for the platform operator; a project's deploy to it is refused) (up to 16 MiB,
+    # +kind+ 'wasm') or an OCI image archive for the sandbox tier (up to 256 MiB, +kind+ 'tar'). Uploading the same
+    # bytes again returns the same key. The envelope's data is { 'artifactKey' => String }.
+    def upload_artifact(bytes, kind)
+      content_type = ARTIFACT_CONTENT_TYPES[kind.to_s]
+      raise ArgumentError, "kind must be 'wasm' or 'tar'" if content_type.nil?
+
+      bytes = bytes.read if bytes.respond_to?(:read)
+      raise ArgumentError, 'bytes must be a String or an IO' unless bytes.is_a?(String)
+
       slug = require_project_slug
-      body = { 'name' => name, 'runtime' => runtime, 'code' => code }
-      body['tier'] = tier if tier
-      body['config'] = config if config
+      HttpTransport.request(config: @config, method: 'POST',
+                            path: UrlGrammar.project_path(slug, 'functions/artifacts'),
+                            raw_body: bytes, headers: { 'content-type' => content_type })
+    end
+
+    # POST /@<slug>/functions — deploy or redeploy from an uploaded artifact.
+    #   Functions run in the sandbox. tier: 'sandbox' (OCI image archive); runtime: bun python go java kotlin dotnet
+    #   swift php ruby rust zig. 'gateway' (WebAssembly) is for the platform operator and is refused for a customer
+    #   deploy; tinygo and assemblyscript run only there, so they cannot be deployed to a project.
+    #   artifact_key: the key +upload_artifact+ returned; version: label for this deploy (1 to 64 characters)
+    def deploy(name:, runtime:, tier:, artifact_key:, version:, description: nil)
+      slug = require_project_slug
+      body = { 'name' => name, 'runtime' => runtime, 'tier' => tier, 'artifactKey' => artifact_key,
+               'version' => version }
+      body['description'] = description unless description.nil?
       HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.project_path(slug, 'functions'), body: body)
     end
 
-    def list(status: nil)
+    # GET /@<slug>/functions (cursor pagination).
+    def list(status: nil, limit: nil, cursor: nil)
       slug = require_project_slug
-      q = status ? { 'status' => status } : nil
+      q = {}
+      q['status'] = status unless status.nil?
+      q['limit'] = limit unless limit.nil?
+      q['cursor'] = cursor unless cursor.nil?
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, 'functions'), query: q)
     end
 
@@ -26,16 +60,25 @@ module K9o
       HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.project_path(slug, "functions/#{enc(name)}"))
     end
 
+    # Retire a function; its name enters a 24h cooldown.
     def delete(name)
       slug = require_project_slug
       HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.project_path(slug, "functions/#{enc(name)}"))
     end
 
-    # Invoke a function; payload passed to the runtime verbatim.
-    def invoke(name, payload)
+    # POST /@<slug>/functions/<name>/invoke. +payload+ is sent as the +payload+ field of the request body and passed
+    # to the function runtime verbatim. Optional controls: +background+ (run asynchronously), +delegation+
+    # ({ 'token' => ..., 'invokeSessionId' => ... }), +on_behalf_of+, +confined_to+.
+    def invoke(name, payload = nil, background: nil, delegation: nil, on_behalf_of: nil, confined_to: nil)
       slug = require_project_slug
+      body = {}
+      body['payload'] = payload unless payload.nil?
+      body['background'] = background unless background.nil?
+      body['delegation'] = delegation unless delegation.nil?
+      body['onBehalfOf'] = on_behalf_of unless on_behalf_of.nil?
+      body['confinedTo'] = confined_to unless confined_to.nil?
       HttpTransport.request(config: @config, method: 'POST',
-                            path: UrlGrammar.project_path(slug, "functions/#{enc(name)}/invoke"), body: payload)
+                            path: UrlGrammar.project_path(slug, "functions/#{enc(name)}/invoke"), body: body)
     end
 
     private
@@ -48,4 +91,79 @@ module K9o
       ::URI.encode_www_form_component(s)
     end
   end
+
+  # Event triggers: k9o.functions.triggers.* run a function when a record is inserted, updated, deleted or upserted
+  # in a collection. They need the project admin role. For triggers on a timetable see +k9o.schedules+.
+  #
+  #   list(name)                                   GET    /@<slug>/functions/<name>/triggers
+  #   create(name, collection:, events:, ...)      POST   /@<slug>/functions/<name>/triggers
+  #   update(name, trigger_id, **fields)           PATCH  /@<slug>/functions/<name>/triggers/<id>
+  #   delete(name, trigger_id)                     DELETE /@<slug>/functions/<name>/triggers/<id>   (204, no body)
+  class FunctionTriggers
+    EVENTS = %w[insert update delete upsert].freeze
+    COLLECTION_RE = /\A[a-zA-Z_][a-zA-Z0-9_]{0,127}\z/.freeze
+    UPDATE_FIELDS = %i[events filter enabled log_ok_invocations].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Every trigger of the function, newest first. Not paginated.
+    def list(name)
+      call('GET', path(name))
+    end
+
+    # Create an event trigger; answers 201 with the trigger. +events+ lists 1 to 4 of insert, update, delete, upsert.
+    # +filter+ is a predicate Hash over the record; leave it out to fire on every matching event.
+    def create(name, collection:, events:, filter: nil, enabled: nil, log_ok_invocations: nil)
+      unless collection.is_a?(String) && COLLECTION_RE.match?(collection)
+        raise ApprovalChecks.invalid('collection must match ^[a-zA-Z_][a-zA-Z0-9_]*$ (1 to 128 characters)',
+                                     collection: collection)
+      end
+
+      body = { 'collection' => collection, 'events' => check_events(events) }
+      body['filter'] = filter unless filter.nil?
+      body['enabled'] = enabled unless enabled.nil?
+      body['logOkInvocations'] = log_ok_invocations unless log_ok_invocations.nil?
+      call('POST', path(name), body: body)
+    end
+
+    # Change a trigger; send at least one of +events+, +filter+, +enabled+, +log_ok_invocations+. A Hash +filter+
+    # replaces the filter and an explicit +filter: nil+ clears it. The collection cannot be changed.
+    def update(name, trigger_id, **fields)
+      unknown = fields.keys - UPDATE_FIELDS
+      raise ApprovalChecks.invalid("unknown field: #{unknown.join(', ')}") unless unknown.empty?
+      raise ApprovalChecks.invalid("patch needs at least one of: #{UPDATE_FIELDS.join(', ')}") if fields.empty?
+
+      body = {}
+      body['events'] = check_events(fields[:events]) if fields.key?(:events)
+      body['filter'] = fields[:filter] if fields.key?(:filter)
+      body['enabled'] = fields[:enabled] if fields.key?(:enabled)
+      body['logOkInvocations'] = fields[:log_ok_invocations] if fields.key?(:log_ok_invocations)
+      call('PATCH', path(name, "/#{ApprovalChecks.id_segment(trigger_id, 'trigger')}"), body: body)
+    end
+
+    # Delete a trigger. Answers 204, so +data+ is nil; deleting again is a 404.
+    def delete(name, trigger_id)
+      call('DELETE', path(name, "/#{ApprovalChecks.id_segment(trigger_id, 'trigger')}"))
+    end
+
+    private
+
+    def check_events(events)
+      list = events.is_a?(Array) ? events.map { |e| e.is_a?(Symbol) ? e.to_s : e } : nil
+      return list if list && list.size.between?(1, 4) && list.all? { |e| EVENTS.include?(e) }
+
+      raise ApprovalChecks.invalid('events must list 1 to 4 of insert, update, delete, upsert', events: events)
+    end
+
+    def call(method, route, body: nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body)
+    end
+
+    def path(name, tail = '')
+      slug = Studio.require_project_slug(@config, 'functions')
+      UrlGrammar.project_path(slug, "functions/#{ApprovalChecks.id_segment(name, 'function')}/triggers#{tail}")
+    end
+  end
 end

data/lib/k9o/gate.rb

@@ -1,64 +1,94 @@
 # frozen_string_literal: true
 
 module K9o
-  # Gate (Identity-Aware Kernel) namespace. Project-scoped.
+  # Gate (Identity-Aware Kernel) namespace. Project-scoped; the gateway closes each body to the fields shown.
   class Gate
     def initialize(config)
       @config = config
     end
 
+    # POST /@<slug>/gate/signup { email, password, displayName? }
     def sign_up(email:, password:, display_name: nil)
       body = { 'email' => email, 'password' => password }
       body['displayName'] = display_name if display_name
       HttpTransport.request(config: @config, method: 'POST', path: gate_path('signup'), body: body)
     end
 
+    # POST /@<slug>/gate/signin { email, password }
+    #
+    # Asks the project which region holds the email first (POST /@<slug>/gate/locate, the email only, no credential),
+    # then sends the password to that region's host if it is a host of your own org and apex, else to the base URL.
+    # A 429 or 503 from that step raises as any gateway error does, nothing else is sent, and it is safe to retry.
     def sign_in(email:, password:)
-      HttpTransport.request(
+      origin = Locate.origin_for(@config, email, gate_path('locate'))
+      out = HttpTransport.request(
         config: @config, method: 'POST', path: gate_path('signin'),
-        body: { 'email' => email, 'password' => password }
+        body: { 'email' => email, 'password' => password }, origin: origin
       )
+      Locate.remember(session_refresh_token(out), origin)
+      out
     end
 
-    def sign_out(refresh_token: nil)
-      body = refresh_token ? { 'refreshToken' => refresh_token } : {}
-      HttpTransport.request(config: @config, method: 'POST', path: gate_path('signout'), body: body)
+    # POST /@<slug>/gate/signout { refreshToken } — the refresh token is required (the gateway answers 400 without it).
+    def sign_out(refresh_token:)
+      out = HttpTransport.request(config: @config, method: 'POST', path: gate_path('signout'),
+                                  body: { 'refreshToken' => refresh_token }, origin: Locate.hint(refresh_token))
+      Locate.forget(refresh_token)
+      out
     end
 
+    # GET /@<slug>/gate/whoami
     def whoami
       HttpTransport.request(config: @config, method: 'GET', path: gate_path('whoami'))
     end
 
+    # POST /@<slug>/auth/sessions/revoke-all
+    #
+    # Ends every live session of the signed-in end user, on every device, this one included. Call it with the end
+    # user's access token as the client's `api_key` (the token `whoami` uses), not a refresh token. The answer's `data`
+    # is `{ revokedCount }`. Each ended session's next refresh raises a KError with code `K9O_SESSION_EXPIRED` and a
+    # `reason` of `"revoked"` in its `context`; access tokens already issued keep working until they expire. An
+    # operator's token raises `K9O_TRUST_ZONE_VIOLATION` (403), and a token issued for another project
+    # `K9O_PROJECT_SCOPE_MISMATCH` (403).
+    def revoke_all_sessions
+      HttpTransport.request(config: @config, method: 'POST', path: project_path('auth/sessions/revoke-all'))
+    end
+
+    # POST /@<slug>/gate/refresh { refreshToken }
+    #
+    # The answer's `data` is `{ accessToken, refreshToken, expiresAt }`. The refresh token you sent stops working: store
+    # the returned `refreshToken` before the next refresh, and refresh one at a time per session. A second call with a
+    # secret that was already used is a replay: the session is revoked and the call raises a KError with code
+    # `K9O_SESSION_EXPIRED` and a `reason` of `"replay"` in its `context`. The newer secret then gets `"revoked"`. The
+    # other reasons are `"inactive"` and `"max_length"`; sign in again.
     def refresh_token(refresh_token:)
-      HttpTransport.request(
+      out = HttpTransport.request(
         config: @config, method: 'POST', path: gate_path('refresh'),
-        body: { 'refreshToken' => refresh_token }
+        body: { 'refreshToken' => refresh_token }, origin: Locate.hint(refresh_token)
       )
+      Locate.rotate(refresh_token, out.respond_to?(:data) ? out.data : nil)
+      out
     end
 
-    def verify_session
-      HttpTransport.request(config: @config, method: 'GET', path: gate_path('verify'))
-    end
+    private
 
-    # The project's hosted sign-in URL and WebAuthn rpId:
-    # GET /@<slug>/gate/hosted. Unauthenticated and cacheable; no credential is
-    # sent even when an api_key is configured. Returns an Envelope whose `data`
-    # is { 'signInUrl' => String, 'rpId' => String }. Take both values as given:
-    # an unknown org, a deleted project and a non-Gate project all answer the
-    # same 404 K9O_PROJECT_NOT_FOUND.
-    def hosted
-      HttpTransport.request(config: @config, method: 'GET', path: gate_path('hosted'), authenticated: false)
+    def session_refresh_token(envelope)
+      data = envelope.respond_to?(:data) ? envelope.data : nil
+      session = data.is_a?(Hash) ? data['session'] : nil
+      session.is_a?(Hash) ? session['refreshToken'] : nil
     end
 
-    private
-
     def gate_path(action)
+      project_path("gate/#{action}")
+    end
+
+    def project_path(suffix)
       raise KError.new(
         code: 'K9O_MISSING_PROJECT_CONTEXT',
         message: 'k9o.gate operations require project_slug bound on the client',
         context: {}
       ) if @config.project_slug.nil? || @config.project_slug.empty?
-      UrlGrammar.project_path(@config.project_slug, "gate/#{action}")
+      UrlGrammar.project_path(@config.project_slug, suffix)
     end
   end
 end

data/lib/k9o/http_transport.rb

@@ -29,12 +29,13 @@ module K9o
   # Per-instance HTTP config bound on K9oClient.
   class HttpClientConfig
     attr_reader :base_url, :api_key, :org_slug, :project_slug, :default_headers, :http_client, :retry_config,
-                :region_mutex
+                :region_mutex, :expected_key_refs
     # Cached regional origin (see K9o::Region); nil until a definite answer.
     attr_accessor :regional_origin
 
     def initialize(base_url:, api_key: nil, org_slug: nil, project_slug: nil, default_headers: {}, http_client: nil,
-                   retry_config: nil)
+                   retry_config: nil, expected_key_refs: nil)
+      @expected_key_refs = expected_key_refs
       @base_url = base_url
       @api_key = api_key
       @org_slug = org_slug
@@ -49,6 +50,8 @@ module K9o
 
   # HTTP transport using Net::HTTP stdlib.
   module HttpTransport
+    # Seconds to wait for a response, as in the Python SDK (120 s read). A long call, such as Rampart `classify` on a long input, can run about 20 s.
+    DEFAULT_READ_TIMEOUT = 120
     RETRYABLE_METHODS = %w[GET HEAD OPTIONS DELETE].freeze
     RETRYABLE_STATUS = [502, 503, 504, 429].freeze
 
@@ -68,13 +71,32 @@ module K9o
     #
     # `authenticated: false` sends NO credential: no api_key bearer, and any
     # authorization / cookie header from `default_headers` or `headers:` is dropped.
-    def request(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil)
+    #
+    # `origin:` sends the request to that origin instead of the client's regional base. Only the end-user credential
+    # flows set it, after the rule in K9o::Locate.
+    #
+    # `bare: true` is for the few public feeds that answer `{ ...fields, meta }` without a `data` wrapper (the Rampart
+    # key feed): the fields come back as `data`.
+    #
+    # `binary: true` is for download routes: a 2xx answer comes back as a K9o::Download (bytes and content type),
+    # not parsed; an error answer is still the JSON error envelope.
+    def request(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil,
+                raw_body: nil, bare: false, binary: false, origin: nil)
       retry_with_backoff(method, config.retry_config || RetryConfig.default) do
         request_once(config: config, method: method, path: path, body: body, query: query, headers: headers,
-                     authenticated: authenticated, multipart: multipart)
+                     authenticated: authenticated, multipart: multipart, raw_body: raw_body, bare: bare,
+                     binary: binary, origin: origin)
       end
     end
 
+    # A response header, or nil (also for response doubles that have no header table).
+    def header_of(response, name)
+      value = response[name]
+      value.is_a?(String) ? value : nil
+    rescue NameError, IndexError, TypeError
+      nil
+    end
+
     # Run a block with retry-with-backoff. Extracted so the retry policy is
     # unit-testable without a live HTTP round-trip.
     def retry_with_backoff(method, retry_config)
@@ -116,8 +138,9 @@ module K9o
     end
 
     # Single-attempt request. `request` wraps this in retry-with-backoff.
-    def request_once(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil)
-      url = "#{Region.resolve_origin(config).sub(%r{/\z}, '')}#{path}"
+    def request_once(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil,
+                     raw_body: nil, bare: false, binary: false, origin: nil)
+      url = "#{(origin || Region.resolve_origin(config)).sub(%r{/\z}, '')}#{path}"
       if query && !query.empty?
         url += '?' + URI.encode_www_form(query)
       end
@@ -125,7 +148,7 @@ module K9o
       uri = URI.parse(url)
       http = config.http_client || ::Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = (uri.scheme == 'https')
-      http.read_timeout = 30
+      http.read_timeout = DEFAULT_READ_TIMEOUT
 
       req_class = case method.to_s.upcase
                   when 'GET' then ::Net::HTTP::Get
@@ -149,7 +172,10 @@ module K9o
         req.delete('cookie')
       end
 
-      if multipart
+      if raw_body
+        # Binary routes: the bytes go unchanged; the caller supplies the content-type in +headers+.
+        req.body = raw_body
+      elsif multipart
         # multipart/form-data: the encoder sets the boundary; never force JSON.
         data, content_type = Multipart.encode(multipart)
         req['content-type'] = content_type
@@ -174,6 +200,10 @@ module K9o
 
       return Envelope.new(data: nil, meta: Meta.new) if status == 204
 
+      if binary && status >= 200 && status < 300
+        return Download.new(body: (response.body || '').b, content_type: header_of(response, 'content-type'))
+      end
+
       begin
         parsed = JSON.parse(response.body || '')
       rescue JSON::ParserError => e
@@ -181,11 +211,17 @@ module K9o
           code: 'K9O_INTERNAL_ERROR',
           message: "Failed to parse JSON response from #{url}: #{e.message}",
           context: { url: url, status: status },
-          status: status
+          status: status,
+          request_id: KError.request_id_from_header(header_of(response, 'x-k9o-request-id'))
         )
       end
 
       if status >= 200 && status < 300
+        if bare && parsed.is_a?(Hash)
+          return Envelope.new(data: parsed.reject { |key, _| key == 'meta' },
+                              meta: Meta.from_wire(parsed['meta'].is_a?(Hash) ? parsed['meta'] : {}))
+        end
+
         unless parsed.is_a?(Hash) && parsed.key?('data') && parsed.key?('meta')
           raise KError.new(
             code: 'K9O_INTERNAL_ERROR',
@@ -198,14 +234,16 @@ module K9o
       end
 
       if parsed.is_a?(Hash) && parsed['code'].is_a?(String) && parsed['message'].is_a?(String)
-        raise KError.from_wire(parsed, status)
+        raise KError.from_wire(parsed, status, retry_after_header: header_of(response, 'retry-after'),
+                                           request_id_header: header_of(response, 'x-k9o-request-id'))
       end
 
       raise KError.new(
         code: 'K9O_INTERNAL_ERROR',
         message: "Upstream returned #{status} with non-KError body",
         context: { url: url, status: status },
-        status: status
+        status: status,
+        request_id: KError.request_id_from_header(header_of(response, 'x-k9o-request-id'))
       )
     end
 
@@ -215,9 +253,9 @@ module K9o
     # sentinel terminates the stream; non-2xx raises KError before any
     # event is yielded.
     #
-    # Per the Ruby async-iteration idiom is Enumerator — caller
+    # The Ruby async-iteration idiom is Enumerator — caller
     # writes `client.compute.llms.invoke_stream(...).each { |chunk| ... }`.
-    def stream_sse(config:, method:, path:, body: nil, query: nil)
+    def stream_sse(config:, method:, path:, body: nil, query: nil, headers: nil, idle_timeout: nil, raw: false)
       url = "#{Region.resolve_origin(config).sub(%r{/\z}, '')}#{path}"
       if query && !query.empty?
         url += '?' + URI.encode_www_form(query)
@@ -227,7 +265,8 @@ module K9o
       Enumerator.new do |yielder|
         http = config.http_client || ::Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = (uri.scheme == 'https')
-        http.read_timeout = 300
+        # The read timeout is a per-read idle limit, not a total limit on the stream.
+        http.read_timeout = idle_timeout || 300
 
         req_class = case method.to_s.upcase
                     when 'GET' then ::Net::HTTP::Get
@@ -236,6 +275,7 @@ module K9o
                     end
         req = req_class.new(uri.request_uri)
         req['accept'] = 'text/event-stream'
+        headers&.each { |k, v| req[k] = v }
         config.default_headers.each { |k, v| req[k] = v }
         req['x-k9o-project-slug'] = config.project_slug if config.project_slug
         req['x-k9o-org-slug'] = config.org_slug if config.org_slug
@@ -257,20 +297,34 @@ module K9o
                 nil
               end
               if parsed.is_a?(Hash) && parsed['code'].is_a?(String) && parsed['message'].is_a?(String)
-                raise KError.from_wire(parsed, status)
+                raise KError.from_wire(parsed, status, retry_after_header: header_of(response, 'retry-after'),
+                                           request_id_header: header_of(response, 'x-k9o-request-id'))
               end
 
               raise KError.new(
                 code: 'K9O_INTERNAL_ERROR',
                 message: "Upstream returned #{status} opening stream",
                 context: { url: url, status: status },
-                status: status
+                status: status,
+                request_id: KError.request_id_from_header(header_of(response, 'x-k9o-request-id'))
               )
             end
 
             buffer = +''
             data_lines = []
+            event_name = nil
+            event_id = nil
+            retry_ms = nil
             flush = lambda do
+              if raw
+                # Raw mode yields every frame as { event:, id:, data:, retry: } (comment lines are dropped).
+                had = !data_lines.empty? || event_name || event_id || retry_ms
+                frame = { event: event_name, id: event_id, data: data_lines.empty? ? nil : data_lines.join("\n"), retry: retry_ms }
+                data_lines = []
+                event_name = event_id = retry_ms = nil
+                yielder << frame if had
+                next true
+              end
               return true if data_lines.empty?
 
               payload = data_lines.join("\n")
@@ -297,6 +351,14 @@ module K9o
                   rest = line[5..]
                   rest = rest[1..] if rest.start_with?(' ')
                   data_lines << rest
+                elsif raw && line.start_with?('event:', 'id:', 'retry:')
+                  field, rest = line.split(':', 2)
+                  rest = rest[1..] if rest.start_with?(' ')
+                  case field
+                  when 'event' then event_name = rest
+                  when 'id' then event_id = rest
+                  else retry_ms = Integer(rest, exception: false)
+                  end
                 end
               end
             end

data/lib/k9o/jcs.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module K9o
+  # The platform's canonical JSON form (the Kilimanjaro JCS code-point profile), implemented here with no dependency.
+  #
+  #   K9o::Jcs.canonicalize({ "b" => 2, "a" => [1, 3] })   # => '{"a":[1,3],"b":2}'
+  #
+  # Object members are sorted by UTF-8 byte order (the same as Unicode code-point order), there is no whitespace,
+  # strings are escaped minimally (+"+ and +\+, the short escapes for backspace, tab, newline, form feed and carriage
+  # return, every other control character as lowercase +\u00xx+; +/+ and every other character are written as they
+  # are), and numbers are integers only: base 10, no exponent, +-0+ written +0+. A fractional number, NaN, an infinity
+  # or an integer whose absolute value is above 2^53 - 1 raises, so a value that cannot be hashed identically
+  # everywhere never gets a hash.
+  module Jcs
+    # Raised for a value that has no canonical form. +kind+ is :non_integer_number, :numeric_ceiling_exceeded or
+    # :unsupported_value.
+    class Error < ArgumentError
+      attr_reader :kind
+
+      def initialize(message, kind = :unsupported_value)
+        super(message)
+        @kind = kind
+      end
+    end
+
+    ESCAPES = {
+      '"' => '\\"', '\\' => '\\\\', "\b" => '\\b', "\t" => '\\t', "\n" => '\\n', "\f" => '\\f', "\r" => '\\r'
+    }.freeze
+    MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+    module_function
+
+    # The canonical form of +value+ as a UTF-8 String.
+    def canonicalize(value)
+      out = +''
+      write(value, out)
+      out.force_encoding(Encoding::UTF_8)
+    end
+
+    # The canonical form as bytes (UTF-8), the preimage to hash.
+    def canonical_bytes(value)
+      canonicalize(value).b
+    end
+
+    def write(value, out)
+      case value
+      when nil then out << 'null'
+      when true then out << 'true'
+      when false then out << 'false'
+      when Integer then out << number(value)
+      when Float then out << number(value)
+      when String then write_string(value, out)
+      when Symbol then write_string(value.to_s, out)
+      when Array
+        out << '['
+        value.each_with_index do |item, index|
+          out << ',' if index.positive?
+          write(item, out)
+        end
+        out << ']'
+      when Hash then write_object(value, out)
+      else
+        raise Error, "#{value.class} has no JSON form"
+      end
+    end
+
+    def write_object(hash, out)
+      members = hash.map { |key, val| [key.is_a?(Symbol) ? key.to_s : key, val] }
+      members.each do |key, _|
+        raise Error, 'object keys must be strings' unless key.is_a?(String)
+      end
+      keys = members.map(&:first)
+      raise Error, 'object has duplicate keys' unless keys.uniq.size == keys.size
+
+      sorted = members.sort_by { |key, _| key.b }
+      out << '{'
+      sorted.each_with_index do |(key, val), index|
+        out << ',' if index.positive?
+        write_string(key, out)
+        out << ':'
+        write(val, out)
+      end
+      out << '}'
+    end
+
+    def write_string(string, out)
+      text = string.encoding == Encoding::UTF_8 ? string : string.encode(Encoding::UTF_8)
+      raise Error, 'string is not valid UTF-8' unless text.valid_encoding?
+
+      out << '"'
+      text.each_char do |ch|
+        if (esc = ESCAPES[ch])
+          out << esc
+        elsif ch.ord < 0x20
+          out << format('\\u%04x', ch.ord)
+        else
+          out << ch
+        end
+      end
+      out << '"'
+    end
+
+    # Integers only, within +/-(2^53 - 1). A float that is a whole number is written as that integer (a JSON reader
+    # that parses +3.0+ sees the integer 3).
+    def number(num)
+      if num.is_a?(Float)
+        raise Error.new('NaN and Infinity have no canonical form', :non_integer_number) unless num.finite?
+        raise Error.new('a fractional number has no canonical form', :non_integer_number) unless num == num.floor
+
+        num = num.to_i
+      end
+      raise Error.new("integer #{num} is above 2^53 - 1", :numeric_ceiling_exceeded) if num.abs > MAX_SAFE_INTEGER
+
+      num.to_s
+    end
+  end
+end