comatype 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11378b390d51323b9426bd34ca59ae31c070eaa2fcaa044fa4e6c34fac481d58
+  data.tar.gz: 36c5c0659ce2dbb3047f6f5288cdc0879441dbefa1927b5ca228cd12a66df7d6
+SHA512:
+  metadata.gz: 5564c686c421770a8f46c998d7b487a16c4ec6bac79fc93ded65f5340ef4bad2d774d86b2c8bb9322a0eca72438b3897b296575c0fc2e18379e6f5a855927242
+  data.tar.gz: 7f232ea4f98d2823afc0eea95c12f6ef2ab626f8301439b64e014692f56bf686b4113c13f3b3f8a05d9842e14a71899d7c8036c126a7ab383823564a95b0702d

data/README.md

@@ -0,0 +1,7 @@
+# comatype
+
+Runtime for Ruby code generated by [Comatype](https://github.com/oldsheeep3/comatype): the client `Comatype::C` and the server `Comatype::S`. It uses only the standard library.
+
+```ruby
+require "comatype"
+```

data/lib/comatype/c.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Comatype
+  # Client. Called like `C.put(ENDPOINT, params: {id: id}, body: user)`.
+  # Argument keys are params: search: headers: body: (a Model instance or a hash keyed by attr).
+  module C
+    Config = Struct.new(:base_url, :wrappers, :cookie_jar, :headers, :timeout, keyword_init: true)
+
+    @lock = Mutex.new
+    # responses of `cache <ttl>` (memory) endpoints
+    @cache = ResponseCache.new
+    # names of cookies carrying cached responses (for clear_cache)
+    @cache_cookies = []
+    @config = Config.new(wrappers: {}, headers: {}, timeout: 30)
+
+    class << self
+      # Call once at startup.
+      #   base_url:  precedence: this > env COMATYPE_BASE_URL > baseUrl in init.comat
+      #   wrappers:  e.g. the generated Init.wrappers(auth: ...). An endpoint that uses a missing wrapper raises an error
+      #   cookies:   true or a CookieJar. `cookie on` endpoints keep Set-Cookie and send it back
+      def init(wrappers: {}, base_url: nil, cookies: nil, headers: {}, timeout: 30)
+        jar = cookies == true ? CookieJar.new : cookies
+        @lock.synchronize do
+          @config = Config.new(base_url: base_url, wrappers: wrappers.transform_keys(&:to_s), cookie_jar: jar, headers: headers, timeout: timeout)
+        end
+      end
+
+      # Drop the cache (memory and what is stored in the cookie jar), e.g. on logout.
+      def clear_cache
+        @cache.clear
+        jar = @lock.synchronize { @config.cookie_jar }
+        @cache_cookies.each { |name| jar&.store(["#{name}=; Path=/; Max-Age=0"]) }
+        @cache_cookies.clear
+      end
+
+      %w[get post put patch delete options query head].each do |m|
+        define_method(m) { |ep, **args| call(m, ep, args) }
+      end
+
+      private
+
+      def call(method, ep, args)
+        raise ConfigError, "C.#{method} に #{ep.method} のエンドポイント（#{ep.module_name}）は渡せません" unless ep.method == method
+
+        conf = @lock.synchronize { @config }
+        chain = ep.wraps.map do |name|
+          conf.wrappers[name] or raise ConfigError, "ラッパー #{name} が init に渡されていません（#{ep.module_name}）"
+        end
+        raw = ep.build_request(args)
+        conf.headers.each { |k, v| raw.headers[k.to_s] = v unless raw.headers.key?(k.to_s) }
+        raw.headers["Accept"] = "application/json" unless raw.headers.key?("Accept")
+        if ep.cookie && conf.cookie_jar
+          # Cache cookies are not sent back to the server
+          conf.cookie_jar.get(raw.path).each { |k, v| raw.cookies[k] = v unless k.start_with?(ResponseCache::COOKIE_PREFIX) }
+        end
+
+        send_fn = ->(r) { transport(ep, conf, r) }
+        nxt = chain.reverse.reduce(send_fn) do |inner, w|
+          ->(r) { w.call(r, inner) }
+        end
+        resp = nxt.call(raw)
+        raise ConfigError, "ラッパーが nil のレスポンスを返しました（#{ep.module_name}）" unless resp.is_a?(RawResponse)
+
+        ep.parse_response(resp)
+      end
+
+      def transport(ep, conf, r)
+        base = conf.base_url || ENV["COMATYPE_BASE_URL"]
+        base = ep.base_url if base.nil? || base.empty?
+        if base.nil? || base.empty?
+          raise ConfigError, "base url がありません（init の base_url、環境変数 COMATYPE_BASE_URL、init.comat の baseUrl のどれかで指定してください）"
+        end
+
+        url = base.sub(%r{/+\z}, "") + r.path
+        unless r.query.empty?
+          url += "?" + r.query.map { |k, v| "#{Cookies.encode(k)}=#{Cookies.encode(v)}" }.join("&")
+        end
+        uri = URI.parse(url)
+        # Cache (GET / QUERY): memory or cookie. The key is the method, URL, body and the declared request headers
+        spec = ep.cache
+        cache_key = nil
+        if spec && (spec.memory? || (spec.cookie? && conf.cookie_jar))
+          cache_key = ResponseCache.client_key(r.method, url, r.body, ep.cache_headers, r.headers)
+          hit =
+            if spec.memory?
+              @cache.get(cache_key)
+            elsif (v = conf.cookie_jar.get("/")[ResponseCache.cookie_name(cache_key)])
+              ResponseCache.decode_cookie(v)
+            end
+          return hit if hit
+        end
+        req = Net::HTTPGenericRequest.new(r.method.upcase, !r.body.empty?, true, uri.request_uri)
+        r.headers.each { |k, v| req.add_field(k, v) }
+        unless r.cookies.empty? || r.headers.key?("Cookie")
+          req["Cookie"] = r.cookies.sort.map { |k, v| "#{k}=#{Cookies.encode(v)}" }.join("; ")
+        end
+        req.body = r.body unless r.body.empty?
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: conf.timeout, read_timeout: conf.timeout) { |h| h.request(req) }
+        out = RawResponse.new(res.code.to_i)
+        res.each_header { |k, _| res.get_fields(k).each { |v| out.headers.add(k, v) } unless k.casecmp?("set-cookie") }
+        out.body = (res.body || "").b
+        out.set_cookies = res.get_fields("set-cookie") || []
+        conf.cookie_jar.store(out.set_cookies) if ep.cookie && conf.cookie_jar && !out.set_cookies.empty?
+        if cache_key && ResponseCache.cacheable?(out)
+          if spec.memory?
+            @cache.set(cache_key, out, spec.ttl_ms)
+          elsif (v = ResponseCache.encode_cookie(out))
+            name = ResponseCache.cookie_name(cache_key)
+            # cookie ttl is in seconds (rounded up)
+            conf.cookie_jar.store(["#{name}=#{v}; Path=/; Max-Age=#{[1, (spec.ttl_ms / 1000.0).ceil].max}"])
+            @cache_cookies << name
+          end
+        end
+        out
+      rescue SystemCallError, IOError, Timeout::Error, SocketError => e
+        raise TransportError, e.message
+      end
+    end
+  end
+end

data/lib/comatype/cache.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Comatype
+  # The `cache` setting of `.comat` (GET / QUERY endpoints only).
+  # mode is :off (never cache) / :memory (in memory for the ttl) / :cookie (in a cookie for the ttl; client only)
+  CacheSpec = Struct.new(:mode, :ttl_ms) do
+    def memory?
+      mode == :memory && ttl_ms.to_i.positive?
+    end
+
+    def cookie?
+      mode == :cookie && ttl_ms.to_i.positive?
+    end
+  end
+
+  # Cache: the in-memory TTL cache, and key / cookie encoding.
+  class ResponseCache
+    # Name prefix of cache cookies. The client does not send cookies with this prefix back to the server
+    COOKIE_PREFIX = "comatype_cache_"
+    # Maximum value length of one cookie. Larger responses are not cached in a cookie
+    COOKIE_MAX = 3800
+
+    def initialize(max = 1000, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @max = max
+      @clock = clock
+      @map = {}
+      @lock = Mutex.new
+    end
+
+    # In-memory cache with ttl (expired entries are dropped on lookup; over the size limit, the oldest are dropped)
+    def get(key)
+      @lock.synchronize do
+        e = @map[key]
+        return nil unless e
+
+        if e[1] <= @clock.call
+          @map.delete(key)
+          return nil
+        end
+        self.class.copy(e[0])
+      end
+    end
+
+    def set(key, res, ttl_ms)
+      @lock.synchronize do
+        @map.delete(key)
+        @map[key] = [self.class.copy(res), @clock.call + (ttl_ms / 1000.0)]
+        @map.shift while @map.size > @max
+      end
+    end
+
+    def clear
+      @lock.synchronize { @map.clear }
+    end
+
+    def size
+      @lock.synchronize { @map.size }
+    end
+
+    class << self
+      def copy(r)
+        o = RawResponse.new(r.status)
+        r.headers.each { |k, v| o.headers.add(k, v) }
+        o.body = r.body.dup
+        o
+      end
+
+      # Whether a response may be cached (2xx, without Set-Cookie)
+      def cacheable?(r)
+        r.status.between?(200, 299) && r.set_cookies.empty?
+      end
+
+      # Client cache key: method, URL (path and query) and body, plus the request headers declared in `.comat`.
+      # Headers added by wrappers or init (Authorization etc.) are not included.
+      def client_key(method, url, body, declared, headers)
+        hs = declared.map(&:downcase).sort.map { |n| "#{n}:#{headers[n]}" }.join("\n")
+        "#{method}\n#{url}\n#{hs}\n\n#{body.dup.force_encoding('UTF-8')}"
+      end
+
+      # Server cache key: an exact match of the request (method, path, query, all headers, body)
+      def server_key(method, target, headers, body)
+        hs = headers.map { |k, v| "#{k.downcase}:#{v}" }.sort.join("\n")
+        "#{method}\n#{target}\n#{hs}\n\n#{body.dup.force_encoding('UTF-8')}"
+      end
+
+      # Derive a cookie name from the key (FNV-1a 64-bit)
+      def cookie_name(key)
+        h = 0xcbf29ce484222325
+        key.each_byte { |b| h = ((h ^ b) * 0x100000001b3) & 0xffffffffffffffff }
+        format("%s%016x", COOKIE_PREFIX, h)
+      end
+
+      # Turn a response into a cookie value (base64url of `status\nname\tvalue\n...\n\nbody`). nil if too large
+      def encode_cookie(r)
+        head = +"#{r.status}\n"
+        r.headers.each { |k, v| head << "#{k}\t#{v}\n" }
+        v = Base64.urlsafe_encode64(head.b + "\n".b + r.body.b, padding: false)
+        v.length <= COOKIE_MAX ? v : nil
+      end
+
+      def decode_cookie(value)
+        raw = Base64.urlsafe_decode64(value).b
+        head, sep, body = raw.partition("\n\n".b)
+        return nil if sep.empty?
+
+        lines = head.force_encoding("UTF-8").split("\n")
+        out = RawResponse.new(Integer(lines[0]))
+        lines[1..].each do |l|
+          k, tab, v = l.partition("\t")
+          out.headers.add(k, v) unless tab.empty?
+        end
+        out.body = body
+        out
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/comatype/check.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Comatype
+  # Validation and constraints (min / max / pattern / oneof).
+  module Check
+    module_function
+
+    # Character-count range (`string(1..50)`)
+    def len(path, s, min, max)
+      n = s.to_s.length
+      raise ValidationError.new(path, "文字数は #{min} 以上にしてください") if min && n < min
+      raise ValidationError.new(path, "文字数は #{max} 以下にしてください") if max && n > max
+    end
+
+    # Value range (`int(0..150)`)
+    def range(path, n, min, max)
+      raise ValidationError.new(path, "値は #{min} 以上にしてください") if min && n < min
+      raise ValidationError.new(path, "値は #{max} 以下にしてください") if max && n > max
+    end
+
+    def pattern(path, s, pattern)
+      re = begin
+        Regexp.new(pattern)
+      rescue RegexpError
+        raise ValidationError.new(path, "pattern #{pattern.inspect} が不正です")
+      end
+      raise ValidationError.new(path, "パターン #{pattern} に一致しません") unless re.match?(s.to_s)
+    end
+
+    def one_of(path, s, values)
+      raise ValidationError.new(path, "#{values.join(' | ')} のどれかにしてください") unless values.include?(s)
+    end
+
+    UUID_RE = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-([0-9a-fA-F])[0-9a-fA-F]{3}-([89abAB])[0-9a-fA-F]{3}-[0-9a-fA-F]{12}\z/.freeze
+    UUID_ANY = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/.freeze
+
+    def uuid(path, s, version)
+      label = version.zero? ? "uuid" : "uuidv#{version}"
+      raise ValidationError.new(path, "#{label} の形式が不正です") unless s.is_a?(String) && UUID_ANY.match?(s)
+      return if version.zero?
+
+      m = UUID_RE.match(s)
+      raise ValidationError.new(path, "#{label} の形式が不正です") unless m && m[1] == version.to_s
+    end
+  end
+end

data/lib/comatype/codec.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Comatype
+  # Converts and validates between Ruby values and JSON trees / strings (path / query / headers) according to a type descriptor.
+  #
+  #   :string :bool :int :int64 :email :phone :uuid :uuidv4 :uuidv7 :date :datetime :time :decimal :url :bytes :json
+  #   [:string, {min: 1, max: 50}]   scalar with constraints (min / max / pattern)
+  #   [:array, t]  [:nullable, t]  [:literal, ["a", "b"]]
+  #   [:ref, a Model/Enum class, or a Proc that returns it]
+  module Codec
+    SCALARS = %i[string bool int int64 email phone uuid uuidv4 uuidv7 date datetime time decimal url bytes json].freeze
+    STRINGY = %i[string email phone uuid uuidv4 uuidv7 date datetime time decimal url].freeze
+
+    module_function
+
+    def fail!(path, reason)
+      raise ValidationError.new(path, reason)
+    end
+
+    def kind_of(t)
+      t.is_a?(Array) ? t[0] : t
+    end
+
+    def resolve(ref)
+      ref.is_a?(Proc) ? ref.call : ref
+    end
+
+    def describe(j)
+      case j
+      when nil then "null"
+      when String then "文字列"
+      when true, false then "真偽値"
+      when Numeric then "数値"
+      when Array then "配列"
+      else "オブジェクト"
+      end
+    end
+
+    # ---- string -> value (shared by JSON strings and path / query / header strings) ----
+
+    def parse_str(kind, s, path)
+      case kind
+      when :string then s
+      when :email
+        fail!(path, "email の形式が不正です") unless s.match?(/\A[^\s@]+@[^\s@]+\.[^\s@]+\z/)
+        s
+      when :phone
+        fail!(path, "phone は E.164 の形式にしてください") unless s.match?(/\A\+[1-9]\d{1,14}\z/)
+        s
+      when :uuid then Check.uuid(path, s, 0) || s.downcase
+      when :uuidv4 then Check.uuid(path, s, 4) || s.downcase
+      when :uuidv7 then Check.uuid(path, s, 7) || s.downcase
+      when :date
+        fail!(path, "date は YYYY-MM-DD の形式にしてください") unless s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        begin
+          Date.strptime(s, "%Y-%m-%d")
+        rescue ArgumentError
+          fail!(path, "date は YYYY-MM-DD の形式にしてください")
+        end
+      when :time
+        fail!(path, "time は HH:MM:SS の形式にしてください") unless s.match?(/\A([01]\d|2[0-3]):[0-5]\d:[0-5]\d\z/)
+        s
+      when :datetime
+        fail!(path, "datetime は RFC 3339 の形式にしてください") unless s.match?(/\A\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})\z/)
+        begin
+          Time.iso8601(s.upcase)
+        rescue ArgumentError
+          fail!(path, "datetime は RFC 3339 の形式にしてください")
+        end
+      when :decimal
+        fail!(path, "decimal は数値の文字列にしてください") unless s.match?(/\A-?\d+(\.\d+)?\z/)
+        BigDecimal(s)
+      when :url
+        u = begin
+          URI.parse(s)
+        rescue URI::InvalidURIError
+          nil
+        end
+        fail!(path, "url は http(s)://host/... の形式にしてください") unless u && u.scheme && u.host
+        u
+      when :bool
+        return true if s == "true"
+        return false if s == "false"
+
+        fail!(path, "真偽値は true か false にしてください")
+      when :int, :int64
+        fail!(path, "整数ではありません") unless s.strip.match?(/\A-?\d+\z/)
+        s.strip.to_i
+      else
+        fail!(path, "#{kind} は path・クエリ・ヘッダに使えない型です")
+      end
+    end
+
+    # value -> string (path, query, headers)
+    def to_wire(kind, v)
+      case kind
+      when :date then v.strftime("%Y-%m-%d")
+      when :datetime then v.utc.iso8601(3)
+      when :decimal then v.to_s("F")
+      else v.to_s
+      end
+    end
+
+    # ---- JSON tree -> value ----
+
+    def decode(t, j, path = "")
+      kind = kind_of(t)
+      case kind
+      when :nullable then j.nil? ? nil : decode(t[1], j, path)
+      when :array
+        fail!(path, "配列にしてください（#{describe(j)} でした）") unless j.is_a?(Array)
+        j.each_with_index.map { |x, i| decode(t[1], x, "#{path}[#{i}]") }
+      when :literal
+        fail!(path, "文字列にしてください（#{describe(j)} でした）") unless j.is_a?(String)
+        Check.one_of(path, j, t[1])
+        j
+      when :ref then resolve(t[1]).decode(j, path)
+      else decode_scalar(kind, t.is_a?(Array) ? t[1] : nil, j, path)
+      end
+    end
+
+    def decode_scalar(kind, constraint, j, path)
+      v =
+        case kind
+        when :bool
+          fail!(path, "真偽値にしてください（#{describe(j)} でした）") unless j == true || j == false
+          j
+        when :int
+          ok = j.is_a?(Integer) || (j.is_a?(Float) && j == j.floor && j.abs < 9e15)
+          fail!(path, "整数にしてください（#{describe(j)} でした）") unless ok
+          j.to_i
+        when :int64
+          fail!(path, "int64 は整数の文字列で送ってください") unless j.is_a?(String) && j.match?(/\A-?\d+\z/)
+          j.to_i
+        when :bytes
+          fail!(path, "文字列にしてください（#{describe(j)} でした）") unless j.is_a?(String)
+          begin
+            Base64.strict_decode64(j)
+          rescue ArgumentError
+            fail!(path, "bytes は base64 の文字列にしてください")
+          end
+        when :json then j
+        else
+          fail!(path, "文字列にしてください（#{describe(j)} でした）") unless j.is_a?(String)
+          parse_str(kind, j, path)
+        end
+      check_constraint(kind, constraint, v, path)
+      v
+    end
+
+    def check_constraint(kind, c, v, path)
+      return unless c
+
+      if STRINGY.include?(kind) && kind != :decimal
+        s = v.is_a?(String) ? v : to_wire(kind, v)
+        Check.len(path, s, c[:min], c[:max]) if c[:min] || c[:max]
+        Check.pattern(path, s, c[:pattern]) if c[:pattern]
+      elsif %i[int int64].include?(kind)
+        Check.range(path, v, c[:min], c[:max])
+      elsif kind == :decimal
+        Check.range(path, v, c[:min], c[:max])
+        Check.pattern(path, v.to_s("F"), c[:pattern]) if c[:pattern]
+      end
+    end
+
+    # ---- value validation (values built by the user; types and constraints) ----
+
+    def validate(t, v, path = "")
+      kind = kind_of(t)
+      case kind
+      when :nullable then v.nil? || validate(t[1], v, path)
+      when :array
+        fail!(path, "配列にしてください") unless v.is_a?(Array)
+        v.each_with_index { |x, i| validate(t[1], x, "#{path}[#{i}]") }
+      when :literal then Check.one_of(path, v, t[1])
+      when :ref then resolve(t[1]).validate_value(v, path)
+      else validate_scalar(kind, t.is_a?(Array) ? t[1] : nil, v, path)
+      end
+    end
+
+    def validate_scalar(kind, constraint, v, path)
+      case kind
+      when :string then fail!(path, "文字列にしてください") unless v.is_a?(String)
+      when :bool then fail!(path, "真偽値にしてください") unless v == true || v == false
+      when :int, :int64 then fail!(path, "整数にしてください") unless v.is_a?(Integer)
+      when :date then fail!(path, "date は Date にしてください") unless v.is_a?(Date)
+      when :datetime then fail!(path, "datetime は Time にしてください") unless v.is_a?(Time)
+      when :decimal then fail!(path, "decimal は BigDecimal にしてください") unless v.is_a?(BigDecimal)
+      when :url then fail!(path, "url は URI にしてください") unless v.is_a?(URI::Generic)
+      when :bytes then fail!(path, "bytes は文字列にしてください") unless v.is_a?(String)
+      when :json then nil
+      else
+        fail!(path, "文字列にしてください") unless v.is_a?(String)
+        parse_str(kind, v, path)
+      end
+      check_constraint(kind, constraint, v, path)
+    end
+
+    # ---- value -> JSON tree (assumed already validated) ----
+
+    def encode(t, v)
+      return nil if v.nil?
+
+      kind = kind_of(t)
+      case kind
+      when :nullable then encode(t[1], v)
+      when :array then v.map { |x| encode(t[1], x) }
+      when :literal then v
+      when :ref then resolve(t[1]).encode_value(v)
+      else encode_scalar(kind, v)
+      end
+    end
+
+    def encode_scalar(kind, v)
+      case kind
+      when :int64 then v.to_s
+      when :bytes then Base64.strict_encode64(v)
+      when :json, :bool, :int, :string then v
+      when :uuid, :uuidv4, :uuidv7 then v.downcase
+      else to_wire(kind, v)
+      end
+    end
+
+    # ---- path, query, headers ----
+
+    # With `split` (headers), an array arrives as one ", "-separated value
+    def from_wire(t, vals, name, split)
+      kind = kind_of(t)
+      case kind
+      when :nullable then vals.empty? ? nil : from_wire(t[1], vals, name, split)
+      when :array
+        fail!(name, "必須です") if vals.empty?
+        items = vals
+        items = (vals[0].strip.empty? ? [] : vals[0].split(",", -1).map(&:strip)) if split && vals.size == 1
+        items.map { |s| from_wire(t[1], [s], name, false) }
+      else
+        fail!(name, "必須です") if vals.empty?
+        s = vals[0]
+        case kind
+        when :ref then resolve(t[1]).from_string(s, name)
+        when :literal
+          Check.one_of(name, s, t[1])
+          s
+        else
+          v = parse_str(kind, s, name)
+          check_constraint(kind, t.is_a?(Array) ? t[1] : nil, v, name)
+          v
+        end
+      end
+    end
+
+    # value -> list of strings (nil is empty)
+    def to_wire_list(t, v)
+      return [] if v.nil?
+
+      kind = kind_of(t)
+      case kind
+      when :nullable then to_wire_list(t[1], v)
+      when :array then v.flat_map { |x| to_wire_list(t[1], x) }
+      when :ref then [resolve(t[1]).to_string(v)]
+      when :literal then [v.to_s]
+      else [to_wire(kind, v)]
+      end
+    end
+  end
+end

data/lib/comatype/cookie.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Comatype
+  # The `cookie <name> { ... }` of init.comat.
+  CookieDef = Struct.new(:name, :http_only, :secure, :same_site, :path, :domain, :max_age, keyword_init: true)
+
+  # A cookie to issue.
+  CookieValue = Struct.new(:value, :delete, :max_age, :path, :domain, keyword_init: true)
+
+  module Cookies
+    EPOCH = "Thu, 01 Jan 1970 00:00:00 GMT"
+
+    module_function
+
+    def encode(s)
+      URI.encode_www_form_component(s.to_s).gsub("+", "%20")
+    end
+
+    def decode(s)
+      URI.decode_www_form_component(s.gsub("+", "%2B"))
+    rescue ArgumentError
+      s
+    end
+
+    def attr(what, v)
+      raise ConfigError, "cookie の #{what} に使えない文字があります: #{v.inspect}" if v.to_s.match?(/[;\r\n]/)
+
+      v
+    end
+
+    # Build a Set-Cookie value. Attributes (HttpOnly etc.) come from init.comat.
+    def serialize(defn, v)
+      raise ConfigError, "このエンドポイントは cookie を発行できません（cookie off、または init.comat に cookie の宣言がありません）" if defn.nil?
+
+      parts = ["#{defn.name}=#{encode(v.delete ? '' : v.value)}"]
+      parts << "Path=#{attr('path', v.path || defn.path || '/')}"
+      d = v.domain || defn.domain
+      parts << "Domain=#{attr('domain', d)}" if d
+      if v.delete
+        parts << "Max-Age=0" << "Expires=#{EPOCH}"
+      else
+        m = v.max_age || defn.max_age
+        if m
+          raise ConfigError, "cookie の maxAge が不正です: #{m}" if m.negative?
+
+          parts << "Max-Age=#{m}"
+        end
+      end
+      parts << "HttpOnly" if defn.http_only
+      parts << "Secure" if defn.secure
+      parts << "SameSite=#{defn.same_site.capitalize}" if defn.same_site
+      parts.join("; ")
+    end
+  end
+
+  # A jar for HTTP clients that do not keep cookies themselves.
+  # Assuming the API is a single origin, Domain is ignored and only Path and expiry are checked.
+  class CookieJar
+    Stored = Struct.new(:value, :path, :expires)
+
+    def initialize
+      @m = {}
+      @lock = Mutex.new
+    end
+
+    # Cookies to send for this path (name -> value).
+    def get(path)
+      @lock.synchronize do
+        now = Time.now
+        @m.delete_if { |_, c| c.expires && c.expires <= now }
+        @m.each_with_object({}) do |(k, c), out|
+          prefix = c.path.end_with?("/") ? c.path : "#{c.path}/"
+          out[k] = c.value if c.path == "/" || path == c.path || path.start_with?(prefix)
+        end
+      end
+    end
+
+    # Take in the response's Set-Cookie (Max-Age=0 deletes).
+    def store(lines)
+      @lock.synchronize do
+        lines.each do |line|
+          segs = line.split(";").map(&:strip)
+          name, value = segs.shift.to_s.split("=", 2)
+          next if name.nil? || name.empty? || value.nil?
+
+          c = Stored.new(Cookies.decode(value), "/", nil)
+          max_age = nil
+          segs.each do |a|
+            k, v = a.split("=", 2)
+            case k.downcase
+            when "path" then c.path = v if v&.start_with?("/")
+            when "max-age" then max_age = Integer(v, exception: false)
+            end
+          end
+          if max_age && max_age <= 0
+            @m.delete(name)
+          else
+            c.expires = Time.now + max_age if max_age
+            @m[name] = c
+          end
+        end
+      end
+    end
+
+    def clear
+      @lock.synchronize { @m.clear }
+    end
+  end
+end