erupt-sdk 0.1.0

data/lib/erupt/http_server.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "socket"
+require "stringio"
+
+module Erupt
+  # A small threaded HTTP/1.1 server (keep-alive, chunked request bodies) that runs a Rack application:
+  # enough for the server-to-server traffic of a node, so the SDK needs no web server gem. To serve a node
+  # from Puma, Rails or Sinatra, mount it there instead.
+  class HttpServer
+    MAX_BODY = 32 << 20
+    MAX_LINE = 16 << 10
+    MAX_HEADERS = 100
+    IDLE_SECONDS = 30
+    REASONS = { 100 => "Continue", 200 => "OK", 400 => "Bad Request", 403 => "Forbidden", 404 => "Not Found",
+                413 => "Payload Too Large", 500 => "Internal Server Error" }.freeze
+
+    BadRequest = Class.new(StandardError)
+
+    def initialize(app, host, port)
+      @app, @port = app, port
+      @server = TCPServer.new(host, port)
+    end
+
+    # Accept until the server is closed (or the thread is interrupted); one thread per connection.
+    def run
+      loop do
+        client = @server.accept
+        Thread.new(client) { |c| connection(c) }
+      end
+    rescue IOError, Errno::EBADF
+      nil # closed
+    end
+
+    def close = @server.close
+
+    private
+
+    def connection(io)
+      loop do
+        env = read_request(io) or break
+        status, headers, body = @app.call(env)
+        keep_alive = keep_alive?(env)
+        head = +"HTTP/1.1 #{status} #{REASONS[status]}\r\n"
+        headers.each { |k, v| Array(v).each { |line| head << "#{k}: #{line}\r\n" } }
+        io.write(head << "connection: #{keep_alive ? "keep-alive" : "close"}\r\n\r\n")
+        body.each { |chunk| io.write(chunk) }
+        body.close if body.respond_to?(:close)
+        break unless keep_alive
+      end
+    rescue BadRequest => e
+      io.write("HTTP/1.1 #{e.message} #{REASONS[e.message.to_i]}\r\ncontent-length: 0\r\nconnection: close\r\n\r\n")
+    rescue IOError, SystemCallError
+      nil # the peer went away
+    ensure
+      io.close
+    end
+
+    def keep_alive?(env)
+      connection = env["HTTP_CONNECTION"].to_s.downcase
+      env["SERVER_PROTOCOL"] == "HTTP/1.1" ? !connection.include?("close") : connection.include?("keep-alive")
+    end
+
+    def read_request(io)
+      return unless IO.select([io], nil, nil, IDLE_SECONDS)
+
+      line = io.gets("\r\n", MAX_LINE) or return
+      method, target, version = line.strip.split(" ", 3)
+      raise BadRequest, "400" unless target && version&.start_with?("HTTP/")
+
+      env = { "REQUEST_METHOD" => method, "SCRIPT_NAME" => "", "SERVER_PROTOCOL" => version,
+              "SERVER_NAME" => "localhost", "SERVER_PORT" => @port.to_s, "REMOTE_ADDR" => io.peeraddr.last,
+              "rack.url_scheme" => "http", "rack.errors" => $stderr }
+      env["PATH_INFO"], env["QUERY_STRING"] = target.split("?", 2)
+      env["QUERY_STRING"] ||= ""
+      read_headers(io, env)
+      io.write("HTTP/1.1 100 Continue\r\n\r\n") if env["HTTP_EXPECT"].to_s.casecmp?("100-continue")
+      env["rack.input"] = StringIO.new(read_body(io, env))
+      env
+    end
+
+    def read_headers(io, env)
+      MAX_HEADERS.times do
+        line = io.gets("\r\n", MAX_LINE) or raise BadRequest, "400"
+        return if line == "\r\n"
+
+        name, value = line.split(":", 2)
+        raise BadRequest, "400" unless value
+
+        key = name.strip.upcase.tr("-", "_")
+        key = "HTTP_#{key}" unless %w[CONTENT_TYPE CONTENT_LENGTH].include?(key)
+        env[key] = env.key?(key) ? "#{env[key]}, #{value.strip}" : value.strip
+      end
+      raise BadRequest, "400"
+    end
+
+    def read_body(io, env)
+      if env["HTTP_TRANSFER_ENCODING"].to_s.downcase.include?("chunked")
+        body = +"".b
+        while (size = io.gets("\r\n", MAX_LINE).to_s.to_i(16)).positive?
+          raise BadRequest, "413" if body.bytesize + size > MAX_BODY
+
+          body << io.read(size).to_s
+          io.read(2)
+        end
+        nil while (trailer = io.gets("\r\n", MAX_LINE)) && trailer != "\r\n"
+        return body
+      end
+      length = Integer(env["CONTENT_LENGTH"] || "0", 10, exception: false) or raise BadRequest, "400"
+      raise BadRequest, "413" if length > MAX_BODY
+
+      length.positive? ? io.read(length).to_s : +"".b
+    end
+  end
+end

data/lib/erupt/model.rb

@@ -0,0 +1,499 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+
+module Erupt
+  # Model declaration: classes that +extend Erupt::Model+, with +field+ and +operation+ declarations, compiled
+  # into erupt build JSON.
+  #
+  # Nothing here re-implements annotation semantics. Every field and operation starts from the template the
+  # Java proxies emit (defaults.json, generated by erupt-test NodeDefaultsTest); a declaration only overrides
+  # values on top of it.
+  DEFAULTS = JSON.parse(File.read(File.join(__dir__, "defaults.json"))).freeze
+
+  IDENTIFIER = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+  # Not an EditType: the SDK's DATE whose picker includes the time, inferred from a Time field
+  DATE_TIME = "DATE_TIME"
+  REFERENCES = [EditType::REFERENCE_TABLE, EditType::REFERENCE_TREE].freeze
+  # many records of another model, stored as the JSON list of their keys
+  COLLECTIONS = [EditType::CHECKBOX, EditType::TAB_TREE, EditType::TRANSFER].freeze
+  # the edit attribute that names a fetchHandler, by the type that fetches options
+  FETCHED = { EditType::CHOICE => "choiceType", EditType::MULTI_CHOICE => "multiChoiceType", EditType::TAGS => "tagsType" }.freeze
+  TIME_PATTERN = /\A(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?)?Z?\z/
+
+  # Ruby class of a field -> the edit type it infers (DateTime before its superclass Date)
+  KINDS = { String => EditType::INPUT, Numeric => EditType::NUMBER, Time => DATE_TIME, DateTime => DATE_TIME,
+            Date => EditType::DATE, TrueClass => EditType::BOOLEAN, boolean: EditType::BOOLEAN }.freeze
+
+  module_function
+
+  def deep_dup(value) = Marshal.load(Marshal.dump(value))
+
+  def merge!(target, override)
+    override.each do |key, value|
+      if value.is_a?(Hash) && target[key].is_a?(Hash)
+        merge!(target[key], value)
+      else
+        target[key] = deep_dup(value)
+      end
+    end
+    target
+  end
+
+  # Raw annotation attributes as JSON data: symbol keys and symbol values become strings.
+  def stringify(value)
+    case value
+    when Hash then value.to_h { |k, v| [k.to_s, stringify(v)] }
+    when Array then value.map { |v| stringify(v) }
+    when Symbol then value.to_s
+    else value
+    end
+  end
+
+  # A DATE_TIME as a local Time: "2026-01-05", "2026-01-05 10:30", "2026-01-05T10:30:00.123Z", Time, Date.
+  def parse_time(value)
+    case value
+    when Time then return value
+    when DateTime then return value.to_time
+    when Date then return Time.new(value.year, value.month, value.day)
+    end
+    m = TIME_PATTERN.match(value.to_s.strip)
+    y, mo, d, h, mi, s = m && m.captures.first(6).map(&:to_i)
+    raise ArgumentError, "illegal date '#{value}'" unless m && Date.valid_date?(y, mo, d) && h < 24 && mi < 60 && s < 60
+
+    Time.new(y, mo, d, h, mi, s + (m[7] ? Rational(m[7].to_i, 10**m[7].size) : 0))
+  end
+
+  # A number as an Integer when it is integral, a Float otherwise.
+  def number(value)
+    n = value.is_a?(String) ? Integer(value, 10, exception: false) || Float(value) : value
+    raise ArgumentError unless n.is_a?(Numeric) && n.finite?
+    return n if n.is_a?(Integer)
+
+    n == n.to_i ? n.to_i : n.to_f
+  rescue ArgumentError, TypeError
+    raise ArgumentError, "illegal number '#{value}'"
+  end
+
+  def json_value(value)
+    case value
+    when Time, DateTime then value.strftime("%Y-%m-%dT%H:%M:%S.%L")
+    when Date then value.strftime("%Y-%m-%d")
+    else value
+    end
+  end
+
+  # One column. +title+ labels both the table column and the form input; +view+ / +edit+ take raw annotation
+  # attributes (<tt>{ inputType: { length: 64 } }</tt>) for anything the shortcuts do not cover.
+  #
+  # A field whose kind is another model class references one of its records: the repository stores the
+  # referenced primary key, the UI shows +label+. +tree+ names the referenced model's parent field and turns
+  # the picker into a tree.
+  #
+  # A field of kind Array or Hash holds a JSON value (MULTI_CHOICE, KEY_VALUE): stored as JSON text by SQL
+  # repositories, served as JSON. +virtual: true+ declares a form-only element (DIVIDE, CALLOUT, EMPTY, GROUP)
+  # that is in the build but never read or written; so is a BUTTON.
+  #
+  # +fetch+, +onchange+, +complete+ and +click+ are the field's own code, run by the node when the server
+  # invokes it (see Node).
+  class Field
+    attr_reader :name, :title, :type, :choices, :label, :tree, :ref, :fetch, :onchange, :complete, :click
+
+    def initialize(name, title = "", kind = nil, type: nil, pk: false, search: false, not_null: false, sortable: false,
+                   table: true, form: true, choices: nil, ref: nil, label: :name, tree: nil, view: {}, edit: {},
+                   virtual: false, fetch: nil, onchange: nil, complete: nil, click: nil)
+      @json, @virtual = [Array, Hash].include?(kind), virtual || type.to_s == EditType::BUTTON
+      @fetch, @onchange, @complete, @click = fetch, onchange, complete, click
+      kind = String if @json
+      @name, @title, @pk, @search, @not_null = name.to_s, title, pk, search, not_null
+      @sortable, @table, @form = sortable, table, form
+      @choices = choices&.to_h { |k, v| [k.to_s, v.to_s] }
+      @ref = ref || (kind if kind.respond_to?(:erupt_model))
+      @label, @tree = label.to_s, tree&.to_s
+      @view, @edit = Erupt.stringify(view), Erupt.stringify(edit)
+      # referenceTableType.dependColumn is @Transient in Java: kept out of the schema check, written into the build
+      @depend_column = @edit["referenceTableType"].delete("dependColumn") if @edit["referenceTableType"].is_a?(Hash)
+      path = "field #{@name}"
+      raise ArgumentError, "#{path}: name must be an identifier" unless IDENTIFIER.match?(@name)
+
+      Schema.check("EditType", type.to_s, "#{path}.type") if type
+      Schema.check("View", @view, "#{path}.view")
+      Schema.check("Edit", @edit, "#{path}.edit")
+      @type = resolve_type(kind, type&.to_s, path) unless pk
+      raise ArgumentError, "#{path}: edit type #{@type} is not supported yet" if @type && !DEFAULTS["fields"].key?(@type)
+
+      check_reference(path) if reference? || collection?
+      if (@fetch && !FETCHED.key?(@type)) || (@complete && @type != EditType::AUTO_COMPLETE) || (@click && @type != EditType::BUTTON)
+        raise ArgumentError, "#{path}: fetch, complete and click belong to CHOICE / MULTI_CHOICE / TAGS, AUTO_COMPLETE and BUTTON"
+      end
+
+      @json ||= collection?
+    end
+
+    %i[pk search not_null sortable table form json virtual].each { |flag| define_method(:"#{flag}?") { instance_variable_get(:"@#{flag}") } }
+
+    def reference? = REFERENCES.include?(@type)
+
+    def collection? = COLLECTIONS.include?(@type)
+
+    # The referenced model, for a reference field.
+    def target = @ref.erupt_model
+
+    def build
+      tpl = Erupt.deep_dup(DEFAULTS["fields"][pk? ? "id" : @type])
+      tpl["fieldName"] = @name
+      tpl["componentValue"] = nil
+      return tpl if pk?
+
+      edit = tpl["eruptFieldJson"]["edit"]
+      # a BUTTON is a form element only: its template has no table column
+      view = tpl["eruptFieldJson"]["views"][0] || {}
+      edit.merge!("title" => @title, "notNull" => not_null?, "show" => form?)
+      edit["search"]["value"] = search?
+      view.merge!("title" => @title, "sortable" => sortable?)
+      view["type"] = "DATE" if @type == EditType::DATE
+      if reference?
+        tpl["fieldReturnName"] = target.name
+        picker = edit[@type == EditType::REFERENCE_TABLE ? "referenceTableType" : "referenceTreeType"]
+        picker.merge!("id" => target.pk, "label" => @label)
+        picker["pid"] = @tree if @tree
+        view["column"] = @label
+      elsif collection?
+        # the server lists a CHECKBOX by the view column, a TAB_TREE by the target's own tree
+        tpl["fieldReturnName"] = target.name
+        view["column"] = @label
+      end
+      edit[FETCHED[@type]]["fetchHandler"] = ["invoke"] if @fetch
+      edit["onchange"] = "invoke" if @onchange
+      Erupt.merge!(edit, @edit)
+      edit["referenceTableType"]["dependColumn"] = @depend_column if @depend_column
+      Erupt.merge!(view, @view)
+      tpl["eruptFieldJson"]["views"] = [] unless table?
+      if @choices # CHOICE, or MULTI_CHOICE over an Array
+        tpl["componentValue"] = @choices.to_a.map do |value, label|
+          { "value" => value, "label" => label, "desc" => nil, "color" => nil, "disable" => false }
+        end
+      end
+      tpl
+    end
+
+    # Turn a JSON value from the browser into the Ruby value stored by the repository.
+    def coerce(value)
+      if reference?
+        # the browser sends the picked record as {<id>: ..., <label>: ...}
+        value = value[target.pk] if value.is_a?(Hash)
+        return target.fields[target.pk].coerce(value)
+      end
+      if collection?
+        # picked records arrive as [{"id": key}] (CHECKBOX) or [{<pk>: key}] (TAB_TREE), and are stored as keys
+        items = value.is_a?(String) ? JSON.parse(value.empty? ? "[]" : value) : value || []
+        raise ArgumentError, "must be a JSON array" unless items.is_a?(Array)
+
+        return items.map { |v| target.fields[target.pk].coerce(v.is_a?(Hash) ? v.values.first : v) }
+      end
+      return nil if value.nil? || value == ""
+      return integer(value) if pk?
+      return json(value) if json?
+
+      case @type
+      when EditType::BOOLEAN then [true, false].include?(value) ? value : %w[true 1].include?(value.to_s.downcase)
+      when EditType::NUMBER, EditType::RATE, EditType::SLIDER then Erupt.number(value)
+      when DATE_TIME then Erupt.parse_time(value)
+      when EditType::DATE then Erupt.parse_time(value).to_date
+      when EditType::CHOICE
+        raise ArgumentError, "illegal option '#{value}'" if @choices && !@choices.key?(value.to_s)
+
+        value.to_s
+      else value.to_s
+      end
+    end
+
+    private
+
+    def json(value)
+      value = JSON.parse(value) if value.is_a?(String)
+      raise ArgumentError, "must be a JSON array or object" unless value.is_a?(Array) || value.is_a?(Hash)
+      raise ArgumentError, "illegal option in #{value}" if @choices && value.is_a?(Array) && !(value.map(&:to_s) - @choices.keys).empty?
+
+      value
+    end
+
+    def integer(value)
+      value.is_a?(String) ? Integer(value.strip, 10) : Integer(value)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "illegal id '#{value}'"
+    end
+
+    def resolve_type(kind, type, path)
+      return type if COLLECTIONS.include?(type)
+      return @tree ? EditType::REFERENCE_TREE : EditType::REFERENCE_TABLE if @ref
+      return type if type
+      return @json ? EditType::MULTI_CHOICE : EditType::CHOICE if @choices || @fetch
+      return EditType::INPUT if kind.nil?
+
+      KINDS.find { |k, _| k == kind || (k.is_a?(Class) && kind.is_a?(Class) && kind <= k) }&.last ||
+        raise(ArgumentError, "#{path}: cannot infer an edit type from #{kind.inspect}; pass type:")
+    end
+
+    def check_reference(path)
+      raise ArgumentError, "#{path}: ref must be a model class declared before this one" unless @ref.respond_to?(:erupt_model)
+      raise ArgumentError, "#{path}: #{target.name} has no primary key" if target.pk.nil?
+
+      [@label, @tree].compact.each do |key|
+        raise ArgumentError, "#{path}: #{target.name} has no field '#{key}'" unless target.fields.key?(key)
+      end
+    end
+  end
+
+  # What an operation block receives: +rows+ (selected records as the repository returned them; empty for
+  # BUTTON mode), +param+ (coerced form values, or nil without a form), +repo+, +model+, +user+.
+  OperationContext = Struct.new(:rows, :param, :repo, :model, :user, keyword_init: true)
+
+  # A row operation declared with +operation+.
+  class Operation
+    attr_reader :code, :title, :mode, :form, :handler
+
+    def initialize(code, title, mode: RowOperationMode::MULTI, icon: nil, tip: "", confirm: true, form: nil, show: nil,
+                   if_expr: "", **raw, &handler)
+      @code, @title, @mode, @icon, @tip = code.to_s, title, mode.to_s, icon, tip
+      @confirm, @form, @show, @if_expr, @raw = confirm, form, show, if_expr, Erupt.stringify(raw)
+      @handler = handler or raise ArgumentError, "operation #{@code}: a block is required"
+      Schema.check("RowOperationMode", @mode, "operation #{@code}.mode")
+      Schema.check("RowOperation", @raw, "operation #{@code}")
+      raise ArgumentError, "operation #{@code}: form must be a model class" if form && !form.respond_to?(:erupt_model)
+    end
+
+    def form_model = @form&.erupt_model
+
+    def visible?(user) = @show.nil? || !!@show.call(user)
+
+    def build
+      tpl = Erupt.deep_dup(DEFAULTS["rowOperation"])
+      tpl.merge!("code" => @code, "title" => @title, "mode" => @mode, "tip" => @tip, "ifExpr" => @if_expr,
+                 "type" => "ERUPT", "eruptClass" => form_model ? form_model.name : "void")
+      tpl["icon"] = @icon if @icon
+      if @confirm == false
+        tpl["callHint"] = "" # the browser runs it without asking
+      elsif @confirm.is_a?(String)
+        tpl["callHint"] = @confirm
+      end
+      Erupt.merge!(tpl, @raw)
+    end
+  end
+
+  # A drill: +erupt+ the linked model, +column+ the source row's column, +join+ the linked model's field holding
+  # it, +condition+ the linkCondition (SQL as written).
+  Drill = Struct.new(:erupt, :column, :join, :condition)
+
+  # A business error shown to the user as a message: raise it from a DataProxy hook or an operation.
+  class Fail < StandardError; end
+
+  # Hooks around a model's data, as erupt's Java +DataProxy+: subclass it, override what you need and pass it
+  # as <tt>erupt ..., data_proxy: ...</tt>. A record is the Hash the repository stores, a row the Hash the
+  # browser reads; change them in place. Raise Fail to refuse with a message.
+  class DataProxy
+    # Default values of the search bar, <tt>condition[field] = value</tt>.
+    def search_condition(condition) = nil
+    # SQL ANDed to a table page's WHERE, as written: <tt>"status <> 'deleted'"</tt>, or with its values bound,
+    # <tt>["owner = ?", [uid]]</tt>. +conditions+ are the search bar's. Only SQL repositories apply it.
+    def before_fetch(conditions) = nil
+    # The rows of a table page, before they are sent.
+    def after_fetch(rows) = nil
+    # The values a new record's form opens with.
+    def add_behavior(record) = nil
+    # A record read by its key, for the edit form or the detail view.
+    def edit_behavior(record) = nil
+    # A record about to be added or updated.
+    def validate(record) = nil
+    def before_add(record) = nil
+    def after_add(record) = nil
+    def before_update(record) = nil
+    def after_update(record) = nil
+    def before_delete(record) = nil
+    def after_delete(record) = nil
+  end
+
+  # What +extend Erupt::Model+ declares about a class.
+  class ModelSpec
+    # fields: stored and served; declared: all of them in order, virtual ones included, for the build
+    attr_reader :cls, :name, :title, :power, :fields, :declared, :operations, :proxies
+    # drill code -> Drill, whose column and joinColumn stay here (@Transient in Java)
+    attr_reader :drills
+
+    def initialize(cls)
+      @cls, @name = cls, cls.name&.split("::")&.last
+      @title, @power, @raw, @order_by, @views = @name, DEFAULTS["power"].dup, {}, nil, {}
+      @fields, @declared, @operations, @proxies, @drills = {}, [], {}, [], {}
+    end
+
+    def configure(title, name, power, order_by, data_proxy, raw)
+      @title, @name, @order_by, @order, @vis = title || @title, (name || @name).to_s, order_by, nil, nil
+      @proxies = Array(data_proxy).map { |p| p.is_a?(Class) ? p.new : p }
+      raise ArgumentError, "#{@name}: data_proxy must be a DataProxy" unless @proxies.all?(DataProxy)
+      @power = DEFAULTS["power"].merge(Erupt.stringify(power || {}))
+      @raw, @views = pull_vis(Erupt.stringify(raw))
+      @raw, @drills = pull_drills(@raw)
+      Schema.check("Erupt", @raw, "erupt #{@name}")
+      raise ArgumentError, "erupt name '#{@name}' must be an identifier" unless IDENTIFIER.match?(@name)
+    end
+
+    def add_field(field)
+      raise ArgumentError, "#{@name}: field '#{field.name}' declared twice" if @declared.any? { |f| f.name == field.name }
+      raise ArgumentError, "#{@name}: at most one primary key" if field.pk? && pk
+
+      @declared << field
+      @fields[field.name] = field unless field.virtual?
+    end
+
+    def add_operation(op)
+      raise ArgumentError, "#{@name}: operation code '#{op.code}' declared twice" if @operations.key?(op.code)
+
+      @operations[op.code] = op
+    end
+
+    # The primary key field's name; a model without one can only serve as an operation form.
+    def pk = @fields.each_value.find(&:pk?)&.name
+
+    # The default table order: "views desc, id" -> [["views", true], ["id", false]], checked against the fields.
+    def order = @order ||= parse_order(@order_by)
+
+    # View code -> [filters, order] the node applies to that view's table queries.
+    def vis = @vis ||= @views.transform_values { |filters, order_by| [filters.map { |f| [f, []] }, parse_order(order_by)] }
+
+    # [field, dependNode] of a @LinkTree: the reference the tree beside the table filters.
+    def link_tree
+      tree = @raw["linkTree"] || {}
+      return unless tree["field"]
+      raise ArgumentError, "#{@name}: linkTree.field '#{tree["field"]}' must be a reference field" unless @fields[tree["field"]]&.reference?
+
+      [tree["field"], tree["dependNode"] == true]
+    end
+
+    # Run one DataProxy hook on every proxy, in declaration order.
+    def hook(name, *args) = @proxies.each { |p| p.public_send(name, *args) }
+
+    # The SQL every proxy's +before_fetch+ adds, as <tt>[[sql, params], ...]</tt>.
+    def filters(conditions)
+      @proxies.filter_map do |p|
+        sql = p.before_fetch(conditions)
+        sql.is_a?(String) ? [sql, []] : [sql[0], Array(sql[1])] if sql && !sql.empty?
+      end
+    end
+
+    # Checks what can only be checked once every field is declared; the node calls it on register.
+    def validate!
+      raise ArgumentError, "erupt name '#{@name}' must be an identifier" unless IDENTIFIER.match?(@name.to_s)
+
+      order
+      vis
+      link_tree
+      self
+    end
+
+    def build_erupt(operations = [])
+      erupt = Erupt.merge!(Erupt.deep_dup(DEFAULTS["erupt"]), "primaryKeyCol" => pk || "id")
+      erupt["rowOperation"] = operations.map(&:build)
+      Erupt.merge!(erupt, @raw)
+      { "eruptName" => @name, "eruptJson" => erupt, "eruptFieldModels" => @declared.map(&:build),
+        "searchCondition" => {}.tap { |c| hook(:search_condition, c) }, "extraRow" => false, "tags" => {} }
+    end
+
+    def build_model(power, user = nil)
+      operations = @operations.values.select { |op| op.visible?(user) }
+      forms = operations.select(&:form).to_h { |op| [op.code, op.form_model.build_erupt] }
+      { "eruptModel" => build_erupt(operations), "power" => power, "tabErupts" => nil, "combineErupts" => nil,
+        "operationErupts" => forms.empty? ? nil : forms }
+    end
+
+    private
+
+    def parse_order(order_by)
+      order_by.to_s.split(",").map(&:strip).reject(&:empty?).map do |part|
+        field, dir, extra = part.split
+        unless @fields.key?(field) && extra.nil? && (dir.nil? || %w[asc desc].include?(dir.downcase))
+          raise ArgumentError, "#{@name}: illegal order_by '#{part}'"
+        end
+
+        [field, dir&.downcase == "desc"]
+      end
+    end
+
+    # +filter+ and +orderBy+ of a +vis+ entry run on the node, as Java keeps them off the build (@Transient):
+    # taken out before the schema check. A view without a +code+ is addressed by its title.
+    def pull_vis(raw)
+      return [raw, {}] unless raw["vis"].is_a?(Array)
+
+      views = {}
+      entries = raw["vis"].map do |entry|
+        next entry unless entry.is_a?(Hash)
+
+        entry = { "code" => entry["title"].to_s }.merge(entry)
+        views[entry["code"]] = [Array(entry.delete("filter")), entry.delete("orderBy")]
+        entry
+      end
+      [raw.merge("vis" => entries), views]
+    end
+
+    # +link.column+ / +link.joinColumn+ of a drill: the source row's column (+id+ by default) and the linked
+    # model's field holding it, applied by the node and kept out of the build. A drill without a +code+ is
+    # addressed by its title.
+    def pull_drills(raw)
+      return [raw, {}] unless raw["drills"].is_a?(Array)
+
+      drills = {}
+      entries = raw["drills"].map do |entry|
+        next entry unless entry.is_a?(Hash)
+
+        link = entry["link"].is_a?(Hash) ? entry["link"].dup : {}
+        column, join = link.delete("column") || "id", link.delete("joinColumn")
+        raise ArgumentError, "#{@name}: drill '#{entry["title"]}' needs link.linkErupt and link.joinColumn" unless join && link["linkErupt"]
+
+        entry = Schema.defaults("Drill").merge("code" => entry["title"].to_s).merge(entry)
+        entry["link"] = Schema.defaults("Link").merge(link)
+        drills[entry["code"]] = Drill.new(link["linkErupt"], column, join.to_s.split(".").first, link["linkCondition"].to_s)
+        entry
+      end
+      [raw.merge("drills" => entries), drills]
+    end
+  end
+
+  # The declaration DSL:
+  #
+  #   class Article
+  #     extend Erupt::Model
+  #     erupt "Article", order_by: "id desc"
+  #     field :id, pk: true
+  #     field :title, "Title", search: true, not_null: true
+  #     operation :publish, "Publish" do |op| ... end
+  #   end
+  module Model
+    def erupt_model = @erupt_model ||= ModelSpec.new(self)
+
+    # +name+ defaults to the class name and is what the server addresses (<tt>node.Name</tt>); +power+
+    # switches features off (<tt>{ delete: false }</tt>); +order_by+ is the default table order, applied by
+    # the node (<tt>"views desc, id"</tt>); +data_proxy+ is one DataProxy or an array of them (classes or
+    # instances), run around every read and write of the model; other keywords are raw +@Erupt+ attributes merged onto the
+    # defaults (<tt>layout: { pageSize: 30 }</tt>); an unknown attribute or value fails here, not in the browser.
+    # A +vis:+ entry may also carry +filter+ (SQL, one or an array) and +orderBy+, applied by the node to that view.
+    def erupt(title = nil, name: nil, power: nil, order_by: nil, data_proxy: nil, **raw)
+      erupt_model.configure(title, name, power, order_by, data_proxy, raw)
+    end
+
+    # +kind+ infers the edit type: String INPUT, Integer / Float NUMBER, +:boolean+ BOOLEAN, Date DATE,
+    # Time DATE_TIME, another model class a reference; +choices:+ makes a CHOICE; +type:+ overrides.
+    def field(name, title = "", kind = nil, **options)
+      erupt_model.add_field(Field.new(name, title, kind, **options))
+    end
+
+    # A row operation; the block receives an OperationContext. A returned string is run as JavaScript in the
+    # browser, so only return code you wrote. +mode+: SINGLE (row button), MULTI (row and toolbar), MULTI_ONLY
+    # (toolbar), BUTTON (toolbar, no rows). +form+: a model class whose fields are asked for before running.
+    # +confirm+: false skips the confirm dialog, a string replaces its text. +show+: <tt>->(user) { ... }</tt>
+    # hides the operation and refuses to run it. +if_expr+: browser-side JS over +item+ that disables (or
+    # hides) the row button. Other keywords are raw +@RowOperation+ attributes.
+    def operation(code, title, **options, &handler)
+      erupt_model.add_operation(Operation.new(code, title, **options, &handler))
+    end
+  end
+end