comatype 0.0.2

data/lib/comatype/endpoint.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Comatype
+  # The request a server handler receives.
+  Request = Struct.new(:params, :search, :headers, :body, :ctx, :raw, keyword_init: true)
+
+  # Endpoint descriptor (held by generated code). Request / response conversion is done here according to the description.
+  class Endpoint
+    attr_reader :method, :path, :module_name, :base_url, :wraps, :cookie, :cookie_def, :cache, :cache_headers, :params, :search, :headers, :body, :responses
+
+    # params / search / headers: Model subclasses (nil if absent), body: type description (nil if absent)
+    # responses: array of Response subclasses
+    def initialize(method:, path:, module_name:, base_url: nil, wraps: [], cookie: false, cookie_def: nil, cache: nil, cache_headers: [],
+                   params: nil, search: nil, headers: nil, body: nil, responses: [])
+      @method = method
+      @path = path
+      @module_name = module_name
+      @base_url = base_url
+      @wraps = wraps.map(&:to_s)
+      @cookie = cookie
+      @cookie_def = cookie_def
+      @cache = cache # CacheSpec (GET / QUERY only; nil means no caching)
+      @cache_headers = cache_headers # names of declared request headers included in the client cache key
+      @params = params
+      @search = search
+      @headers = headers
+      @body = body
+      @responses = responses.to_h { |r| [r.status, r] }
+    end
+
+    # ---- client: arguments (params: search: headers: body:) -> RawRequest ----
+
+    def build_request(args)
+      unknown = args.keys - %i[params search headers body]
+      raise ArgumentError, "#{module_name}: 知らない引数 #{unknown.join(', ')}" unless unknown.empty?
+
+      raw = RawRequest.new(method, path)
+      if @params
+        p = @params.coerce(args[:params]) || @params.new
+        p.validate
+        segs = raw.path.split("/", -1).map do |s|
+          next s unless s.start_with?(":")
+
+          name = s[1..]
+          f = @params.fields.find { |x| x.json == name }
+          v = f && Codec.to_wire_list(f.type, p.public_send(f.attr)).first
+          raise ValidationError.new(name, "必須です") if v.nil? || v.empty?
+
+          raw.params[name] = v
+          Cookies.encode(v)
+        end
+        raw.path = segs.join("/")
+      end
+      if @search
+        s = @search.coerce(args[:search]) || @search.new
+        s.validate
+        @search.fields.each { |f| Codec.to_wire_list(f.type, s.public_send(f.attr)).each { |v| raw.query << [f.json, v] } }
+      end
+      if @headers
+        h = @headers.coerce(args[:headers]) || @headers.new
+        h.validate
+        write_headers(raw.headers, @headers, h)
+      end
+      if @body
+        raise ValidationError.new("body", "必須です") if args[:body].nil?
+
+        b = args[:body]
+        b = b.is_a?(Model) ? b : coerce_body(@body, b)
+        Codec.validate(@body, b, "")
+        raw.body = JSON.generate(Codec.encode(@body, b)).b
+        raw.headers["Content-Type"] = "application/json"
+      end
+      raw
+    end
+
+    # ---- client: RawResponse -> Response ----
+
+    def parse_response(raw)
+      cls = @responses[raw.status] or raise UnexpectedStatusError.new(raw.status, raw.body)
+      body = nil
+      if cls.body_type
+        raise ValidationError.new("body", "必須です") if raw.body.empty?
+
+        body = Codec.decode(cls.body_type, Wire.parse_json(raw.body, "body"), "body")
+      end
+      headers = nil
+      if cls.headers_class
+        headers = cls.headers_class.from_wire(->(n) { raw.headers.get_all(n) }, split: true)
+        headers.validate
+      end
+      cls.new(body, headers: headers)
+    end
+
+    # ---- server: RawRequest -> Request ----
+
+    def parse_request(raw)
+      req = Request.new(ctx: raw.ctx, raw: raw)
+      req.params = @params&.from_wire(->(n) { raw.params.key?(n) ? [raw.params[n]] : [] })&.tap(&:validate)
+      req.search = @search&.from_wire(->(n) { raw.query_all(n) })&.tap(&:validate)
+      req.headers = @headers&.from_wire(->(n) { raw.headers.get_all(n) }, split: true)&.tap(&:validate)
+      if @body
+        raise ValidationError.new("body", "必須です") if raw.body.empty?
+
+        req.body = Codec.decode(@body, Wire.parse_json(raw.body, "body"), "body")
+      end
+      req
+    end
+
+    # ---- server: Response -> RawResponse ----
+
+    def build_response(res)
+      cls = @responses[res.status]
+      raise ConfigError, "s#{res.status} は #{module_name} に宣言されていません" unless cls && res.is_a?(cls)
+
+      out = RawResponse.new(res.status)
+      if cls.body_type
+        Codec.validate(cls.body_type, res.body, "")
+        out.body = JSON.generate(Codec.encode(cls.body_type, res.body)).b
+        out.headers["Content-Type"] = "application/json"
+      end
+      if cls.headers_class
+        res.headers.validate
+        write_headers(out.headers, cls.headers_class, res.headers)
+      end
+      out.set_cookies << Cookies.serialize(@cookie_def, res.cookie) if res.cookie
+      out
+    end
+
+    private
+
+    def write_headers(headers, klass, model)
+      klass.fields.each do |f|
+        vs = Codec.to_wire_list(f.type, model.public_send(f.attr))
+        headers[f.json] = vs.join(", ") unless vs.empty?
+      end
+    end
+
+    # Hash / array values other than the body go straight through the type description (Model references are built from hashes)
+    def coerce_body(t, v)
+      kind = Codec.kind_of(t)
+      case kind
+      when :ref
+        k = Codec.resolve(t[1])
+        k.respond_to?(:coerce) ? k.coerce(v) : v
+      when :array then v.map { |x| coerce_body(t[1], x) }
+      when :nullable then v.nil? ? nil : coerce_body(t[1], v)
+      else v
+      end
+    end
+  end
+end

data/lib/comatype/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Comatype
+  class Error < StandardError; end
+
+  # An input or output does not match the .comat type.
+  class ValidationError < Error
+    attr_reader :path, :reason
+
+    def initialize(path, reason)
+      @path = path
+      @reason = reason
+      super(path.empty? ? reason : "#{path}: #{reason}")
+    end
+
+    def self.join(path, name)
+      path.empty? ? name.to_s : "#{path}.#{name}"
+    end
+  end
+
+  # A status not declared in .comat was returned.
+  class UnexpectedStatusError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body = body
+      super("想定していないステータス #{status} が返りました")
+    end
+  end
+
+  # Configuration error (a wrapper was not passed, no base url, etc.).
+  class ConfigError < Error; end
+
+  # The request failed.
+  class TransportError < Error; end
+end

data/lib/comatype/model.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Comatype
+  # A named string enum. Declare values with `values "admin", "member"` (constants are uppercase: Role::ADMIN).
+  class Enum
+    class << self
+      def values(*vals)
+        return @values if vals.empty?
+
+        @values = vals.freeze
+        vals.each { |v| const_set(v.to_s.upcase.gsub(/[^A-Z0-9]/, "_").sub(/\A(\d)/, 'V_\1'), v) }
+      end
+
+      def decode(j, path = "")
+        raise ValidationError.new(path, "文字列にしてください（#{Codec.describe(j)} でした）") unless j.is_a?(String)
+
+        Check.one_of(path, j, values)
+        j
+      end
+
+      def validate_value(v, path)
+        Check.one_of(path, v, values)
+      end
+
+      def encode_value(v)
+        v
+      end
+
+      def from_string(s, name)
+        Check.one_of(name, s, values)
+        s
+      end
+
+      def to_string(v)
+        v.to_s
+      end
+    end
+  end
+
+  # Object type. Subclasses declare `field :attr, "jsonName", type, optional: true`.
+  # Parent of generated types (named types, params / search / headers, body).
+  class Model
+    Field = Struct.new(:attr, :json, :type, :optional)
+
+    class << self
+      def fields
+        @fields ||= []
+      end
+
+      def inherited(sub)
+        super
+        sub.instance_variable_set(:@fields, fields.dup)
+      end
+
+      def field(attr, json, type, optional: false)
+        fields << Field.new(attr, json, type, optional)
+        attr_accessor attr
+      end
+
+      def nullable?(t)
+        t.is_a?(Array) && t[0] == :nullable
+      end
+
+      # JSON tree -> instance
+      def decode(j, path = "")
+        raise ValidationError.new(path, "オブジェクトにしてください（#{Codec.describe(j)} でした）") unless j.is_a?(Hash)
+
+        kw = {}
+        fields.each do |f|
+          p = ValidationError.join(path, f.json)
+          if !j.key?(f.json) || (j[f.json].nil? && f.optional)
+            raise ValidationError.new(p, "必須です") unless f.optional || nullable?(f.type)
+
+            kw[f.attr] = nil
+            next
+          end
+          kw[f.attr] = Codec.decode(f.type, j[f.json], p)
+        end
+        new(**kw)
+      end
+
+      # Build from path / query / header values (a call that returns name -> list of strings)
+      def from_wire(lookup, split: false)
+        kw = {}
+        fields.each do |f|
+          vals = lookup.call(f.json)
+          if vals.empty?
+            raise ValidationError.new(f.json, "必須です") unless f.optional || nullable?(f.type)
+
+            kw[f.attr] = nil
+          else
+            kw[f.attr] = Codec.from_wire(f.type, vals, f.json, split)
+          end
+        end
+        new(**kw)
+      end
+
+      # Entry point for validating nested values
+      def validate_value(v, path)
+        raise ValidationError.new(path, "#{name} にしてください") unless v.is_a?(self)
+
+        v.validate(path)
+      end
+
+      def encode_value(v)
+        v.encode
+      end
+
+      # Turn a hash (keyed by attr) or an existing instance into an instance of this class
+      def coerce(v)
+        return v if v.is_a?(self) || v.nil?
+        return new(**v.transform_keys(&:to_sym)) if v.is_a?(Hash)
+
+        raise ArgumentError, "#{name} かハッシュを渡してください（#{v.class}）"
+      end
+    end
+
+    def initialize(**kw)
+      unknown = kw.keys - self.class.fields.map(&:attr)
+      raise ArgumentError, "#{self.class.name} に無いキー: #{unknown.join(', ')}" unless unknown.empty?
+
+      self.class.fields.each { |f| instance_variable_set("@#{f.attr}", kw[f.attr]) }
+    end
+
+    # Check that it matches the .comat type (including constraints)
+    def validate(path = "")
+      self.class.fields.each do |f|
+        v = instance_variable_get("@#{f.attr}")
+        p = ValidationError.join(path, f.json)
+        if v.nil?
+          raise ValidationError.new(p, "必須です") unless f.optional || self.class.nullable?(f.type)
+
+          next
+        end
+        Codec.validate(f.type, v, p)
+      end
+      true
+    end
+
+    # JSON tree (Hash with string keys). Validated before it is built
+    def encode
+      validate
+      self.class.fields.each_with_object({}) do |f, h|
+        v = instance_variable_get("@#{f.attr}")
+        next if v.nil? && f.optional
+
+        h[f.json] = Codec.encode(f.type, v)
+      end
+    end
+
+    def to_h
+      self.class.fields.to_h { |f| [f.attr, instance_variable_get("@#{f.attr}")] }
+    end
+
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+
+    def to_s
+      "#<#{self.class.name} #{to_h.inspect}>"
+    end
+    alias inspect to_s
+  end
+end

data/lib/comatype/raw.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Comatype
+  # Case-insensitive headers (the same name may appear several times).
+  class Headers
+    include Enumerable
+
+    def initialize
+      @items = []
+    end
+
+    def [](name)
+      kv = @items.find { |k, _| k.casecmp?(name) }
+      kv&.last
+    end
+
+    def get_all(name)
+      @items.select { |k, _| k.casecmp?(name) }.map(&:last)
+    end
+
+    # Replace entries with the same name
+    def []=(name, value)
+      @items.reject! { |k, _| k.casecmp?(name) }
+      @items << [name, value.to_s]
+    end
+
+    # Add, keeping entries with the same name
+    def add(name, value)
+      @items << [name, value.to_s]
+    end
+
+    def key?(name)
+      !self[name].nil?
+    end
+
+    def each(&block)
+      @items.each(&block)
+    end
+  end
+
+  # The raw request a wrapper sees (the on-the-wire form, with no per-endpoint types).
+  class RawRequest
+    # method: lowercase, path: with params filled in (client) / the path that arrived (server)
+    attr_accessor :method, :path, :headers, :query, :params, :body, :cookies, :ctx
+
+    def initialize(method, path)
+      @method = method
+      @path = path
+      @headers = Headers.new
+      @query = []
+      @params = {}
+      @body = "".b
+      @cookies = {}
+      @ctx = {} # values added by server wrappers (wrapper name -> value)
+    end
+
+    def cookie(name)
+      @cookies[name.to_s]
+    end
+
+    def query_all(name)
+      @query.select { |k, _| k == name }.map(&:last)
+    end
+  end
+
+  # The raw response a wrapper sees (the on-the-wire form).
+  class RawResponse
+    # set_cookies: Set-Cookie lines to send (server) / lines received (client), err: a cause not included in the response
+    attr_accessor :status, :headers, :body, :set_cookies, :err
+
+    def initialize(status)
+      @status = status
+      @headers = Headers.new
+      @body = "".b
+      @set_cookies = []
+      @err = nil
+    end
+
+    def self.json(status, tree)
+      r = new(status)
+      unless tree.nil?
+        r.body = JSON.generate(tree).b
+        r.headers["Content-Type"] = "application/json"
+      end
+      r
+    end
+
+    # Turn the server's own error into a 500. Details are not shown to the client.
+    def self.error(cause)
+      r = new(500)
+      r.body = '{"code":"internal_error","message":"Internal Server Error"}'.b
+      r.headers["Content-Type"] = "application/json"
+      r.err = cause.to_s
+      r
+    end
+  end
+end

data/lib/comatype/response.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Comatype
+  # Parent of the per-status responses. Generated code declares `class S200 < Comatype::Response`.
+  #   status 200 / body_type <type description> / headers_class <Model subclass>
+  # The server returns `S200.new(body, headers: {...})`; the client receives an instance of this class.
+  class Response
+    class << self
+      def status(n = nil)
+        n.nil? ? @status : (@status = n)
+      end
+
+      def body_type(t = nil)
+        t.nil? ? @body_type : (@body_type = t)
+      end
+
+      def headers_class(k = nil)
+        k.nil? ? @headers_class : (@headers_class = k)
+      end
+
+      # Build the RawResponse a wrapper returns (no headers / cookies). Used by the generated `Init.s401(body)`
+      def raw(body = nil)
+        out = RawResponse.new(status)
+        if body_type
+          Codec.validate(body_type, body, "")
+          out.body = JSON.generate(Codec.encode(body_type, body)).b
+          out.headers["Content-Type"] = "application/json"
+        end
+        out
+      end
+    end
+
+    attr_reader :body, :headers, :cookie
+
+    # A status without a body is `S204.new`; headers only is `S200.new(headers: {...})`
+    def initialize(body = nil, headers: nil)
+      if body.nil? && self.class.body_type && !(self.class.body_type.is_a?(Array) && self.class.body_type[0] == :nullable)
+        raise ArgumentError, "#{self.class.name} にはボディが要ります"
+      end
+      raise ArgumentError, "#{self.class.name} にはボディを渡せません" if !body.nil? && self.class.body_type.nil?
+
+      @body = body
+      hc = self.class.headers_class
+      raise ArgumentError, "#{self.class.name} にはヘッダを渡せません" if headers && hc.nil?
+
+      @headers = hc ? (hc.coerce(headers) || hc.new) : nil
+      @cookie = nil
+    end
+
+    def status
+      self.class.status
+    end
+
+    # Issue a cookie from init.comat (server)
+    def with_cookie(value, max_age: nil, path: nil, domain: nil)
+      @cookie = CookieValue.new(value: value, delete: false, max_age: max_age, path: path, domain: domain)
+      self
+    end
+
+    # Delete a cookie (server)
+    def clear_cookie
+      @cookie = CookieValue.new(value: "", delete: true)
+      self
+    end
+
+    def to_s
+      "#<#{self.class.name} body=#{@body.inspect} headers=#{@headers.inspect}>"
+    end
+    alias inspect to_s
+  end
+end