flezha 0.1.0-aarch64-linux

data/lib/flezha/logger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Flezha
+  # The SDK's diagnostics, through a logger the host supplies.
+  #
+  # The default writes to standard error at `warn` and above, which is what the
+  # other SDKs' defaults amount to: a runner that says nothing about a wedge is
+  # the failure mode the diagnostics exist to close, and one that narrates
+  # every activation is noise. No observability dependency — a host that wants
+  # spans or structured fields supplies its own logger.
+  class ConsoleLogger
+    ORDER = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+
+    def initialize(level = :warn)
+      @level = ORDER.fetch(level.to_sym, 2)
+    end
+
+    ORDER.each_key do |level|
+      define_method(level) { |message| write(level, message) }
+    end
+
+    private
+
+    def write(level, message)
+      return if ORDER[level] < @level
+
+      $stderr.puts("[flezha] #{message}")
+    rescue StandardError
+      # A logger must never take the process down. The case that reaches here
+      # is a closed standard stream during shutdown — the harness closes the
+      # runner's pipes to stop it — where writing raises EPIPE, and an
+      # unhandled stream error would turn a clean drain into a crash.
+      nil
+    end
+  end
+
+  # Per-Ractor rather than a bare global, for the reason every handle in this
+  # SDK is: a Ractor executor must be addable without restructuring, and a
+  # shared mutable global is exactly what would have to be unpicked.
+  def self.log
+    Ractor.current[:flezha_logger] ||= ConsoleLogger.new(ENV.fetch("FLEZHA_LOG_LEVEL", "warn"))
+  end
+
+  def self.log=(logger)
+    Ractor.current[:flezha_logger] = logger
+  end
+
+  NOTICE_LEVELS = { "info" => :info, "warn" => :warn }.freeze
+
+  # Write the core's notices, as `take_notices` answers them, through the SDK's
+  # logger; an error, and the local-mode banner (`always`), at `error`, which no
+  # level hides.
+  def self.log_notices(taken)
+    taken.each { |level, _target, text| log.public_send(NOTICE_LEVELS.fetch(level, :error), text) }
+  end
+end

data/lib/flezha/native.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+require_relative "version"
+
+module Flezha
+  # The compiled veneer over `flz_core`'s C ABI, and the two rules that hold
+  # around it: one context per process, and no core call from a process that
+  # did not start it.
+  #
+  # `Flezha::Native` itself is defined by the extension (`ruby_glue.rs`). This
+  # wrapper adds no ABI surface — every method below forwards to exactly one
+  # veneer function — it adds the fork guard, which is a host rule rather than
+  # a core one.
+  class Core
+    # An absent extension is an installation defect rather than a refusal, and
+    # nothing is left to render a catalogue message with, so it stays a
+    # `LoadError`.
+    def self.load_extension
+      # Ruby derives `Init_flz_core_ffi` from the basename, which is what the
+      # veneer exports. A precompiled gem carries one library per Ruby minor,
+      # under `lib/flezha/<minor>/`; a source build puts its one in `lib/flezha/`.
+      per_minor = "flezha/#{RUBY_VERSION[/\A\d+\.\d+/]}/flz_core_ffi"
+      begin
+        require per_minor
+      rescue LoadError => e
+        # Only an absent file falls through; one that is there and will not
+        # load is the error to report.
+        raise unless e.path == per_minor
+
+        require "flezha/flz_core_ffi"
+      end
+    rescue LoadError => e
+      raise LoadError,
+            "the flezha native extension could not be loaded (#{e.message}). Install a " \
+            "precompiled platform gem, or build the source gem with cargo and git."
+    end
+
+    # The JSON error document the catalogue renders for `code` and `details`:
+    # what `Flezha::Error` is built from, for a refusal this SDK makes itself.
+    def self.error_document(code, details)
+      load_extension
+      Native.error_document(code.to_s, JSON.generate(details))
+    end
+
+    # Create the process context, negotiating the activation schema version
+    # before any controller connection is attempted.
+    def self.create
+      load_extension
+      # The first take starts holding the core's notices for this host's
+      # drains; anything an earlier context left is written now.
+      Flezha.log_notices(Native.take_notices)
+      Native.context_new(ACTIVATION_SCHEMA_VERSION)
+      new
+    end
+
+    # The entry points that take no context and therefore no guard: they read
+    # a process-global clock, which a fork does not break. Reachable before
+    # `create`, which is what lets a runner answer before it boots.
+    def self.context_free
+      load_extension
+      Native
+    end
+
+    def initialize
+      # Recorded at construction rather than at `start`, so a fork between the
+      # two is caught by the same guard.
+      @owner_pid = Process.pid
+    end
+
+    # The process that owns the core. A fork after this point does not carry
+    # the core's Rust threads — transport, flusher, the runner loop — so the
+    # child would connect to nothing and serve nothing, silently.
+    def guard!
+      return if Process.pid == @owner_pid
+
+      raise Error.new("runtime.forked_process", owner: @owner_pid, pid: Process.pid)
+    end
+
+    # Every ABI entry point a running host reaches, in the veneer's own
+    # spelling.
+    #
+    # Generated rather than written out fifteen times over: the fork guard then
+    # provably applies to all of them — there is no site left to forget it at —
+    # and `native_test.rb` asserts this list is exactly what the veneer
+    # exports, so an entry point added there and not here is a red build rather
+    # than a method that quietly does not exist.
+    ENTRY_POINTS = %i[
+      declare_class undeclare_class check_class start poll complete abandon shutdown
+      pool_open pool_supervise pool_left
+      local_start local_on_sink local_feed local_next_output local_run_until_idle local_stop
+      watch_stdin_eof spawn_request spawn_result part effect_begin effect_end effect_release
+      admin_call send_message relays monotonic_nanos last_error take_notices
+    ].freeze
+
+    ENTRY_POINTS.each do |entry|
+      define_method(entry) do |*args|
+        guard!
+        Native.public_send(entry, *args)
+      end
+    end
+
+    # The one entry point not named after its own: `context_free` releases what
+    # `context_new` created, and `create` is what made this object.
+    def free
+      guard!
+      Native.context_free
+    end
+  end
+end

data/lib/flezha/relay.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "builder"
+require_relative "declarative"
+require_relative "errors"
+require_relative "tasklet"
+
+module Flezha
+  # The base an authored relay subclasses. Its class body declares the
+  # factory id and one body: a `channels` graph, or, for the single-tasklet
+  # short form, that tasklet's `run` instance method, which emits through its
+  # `ctx` as a tasklet's does. `spec` resolves the declaration once.
+  class Relay
+    extend Declarative
+    # A short form's tasklet settings, handed to the tasklet it generates.
+    extend TaskletSettings
+
+    # The channels graph. The block receives the builder.
+    block_setting :channels
+    # The short form's entry channel name, its codec and its optional plugin
+    # output. A full form names its channels in `channels` instead.
+    SHORT_FORM_KEYS = %i[input codec output].freeze
+    setting(*SHORT_FORM_KEYS)
+    # The declarations only a short form reads.
+    SHORT_FORM_ONLY = (SHORT_FORM_KEYS + TaskletSettings::NAMES).freeze
+    # The class settings, the tree's own data: `run :steps`,
+    # `run steps: { each: :per_input }`, `durable false`,
+    # `durable local: { sleep_after: 2_000 }`. A finished instance keeps
+    # nothing unless the level sets `keep_finished` to hours, or to `true` for
+    # the controller's window (72 hours by default), so `flz relay info` can
+    # still show its Cells and result. Either form takes them; the core reads
+    # the tree when the class registers and refuses a misplaced setting by name.
+    setting :run, :durable, :max_duration_ms, :description
+    # `factory_id` is deliberately NOT inherited: two relays cannot share
+    # one, and a subclass silently taking its parent's would be refused by the
+    # core at declare time rather than here.
+
+    class << self
+      def factory_id(id = nil)
+        return @factory_id if id.nil?
+
+        @factory_id = id.to_s
+      end
+
+      def spec
+        @spec ||= build_spec
+      end
+
+      # The tasklet a short form generates, or `nil` for a full form. Named
+      # after the factory id, verbatim: a tasklet's name is part of every
+      # cell's state path, so the full form that replaces this one keeps
+      # its cells by naming its tasklet the same.
+      def tasklet
+        return nil unless short_form?
+
+        check_declaration!
+        @tasklet ||= Class.new(Tasklet).tap do |generated|
+          relay = self
+          generated.tasklet_name(@factory_id)
+          generated.define_singleton_method(:body) { relay }
+          hand_down(generated, TaskletSettings::NAMES)
+        end
+      end
+
+      # The refusals a class earns before anything is built, raised by
+      # `Runner#register_factory` at the call the author wrote and again when
+      # the spec is built.
+      def check_declaration!
+        # A factory id is written, never derived from the class.
+        raise Error.new("topology.missing_factory_id", relay: to_s) unless @factory_id
+
+        if short_form?
+          raise Error.new("topology.short_form_with_topology", factory_id: @factory_id) if channels
+        elsif channels
+          refuse_written("topology.short_form_field_on_full_form", SHORT_FORM_ONLY)
+        else
+          raise Error.new("topology.missing_body", declaration: "relay '#{@factory_id}'",
+                                                   body: "`channels`, or one tasklet's `run` as the short form")
+        end
+      end
+
+      private
+
+      # A short form carries its one tasklet's `run` body instead of a
+      # `channels` graph.
+      def short_form? = method_defined?(:run)
+
+      # Refuse the declarations among +names+ this class wrote, naming each.
+      def refuse_written(code, names)
+        names = written(names).keys
+        return if names.empty?
+
+        raise Error.new(code, factory_id: @factory_id, fields: names.map { |name| "`#{name}`" })
+      end
+
+      def build_builder
+        check_declaration!
+        builder = ChannelBuilder.new(@factory_id)
+        short_form? ? wire_short_form(builder) : channels.call(builder)
+        builder
+      end
+
+      # `input -> tasklet`, and on to the plugin output when one is declared.
+      def wire_short_form(builder)
+        edge = builder.input(input || "input", codec: codec).into(tasklet)
+        edge.output(output) if output
+      end
+
+      # The graph and the settings tree as written: the core judges the tree
+      # and refuses a misplaced setting by name.
+      def build_spec
+        # Sealed before the channels are read: filing every declared sequence
+        # on its channel is what can still create one.
+        builder = build_builder.seal
+        ClassSpec.new(
+          factory_id: @factory_id, description: description, max_duration_ms: max_duration_ms,
+          run: Flezha.tree_json(run), durable: Flezha.tree_json(durable),
+          tasklets: builder.tasklets, channels: builder.channels
+        )
+      end
+    end
+  end
+
+  # A settings tree as its JSON: symbols are strings, `nil` stays absent.
+  def self.tree_json(tree)
+    case tree
+    when Hash then tree.to_h { |name, member| [name.to_s, tree_json(member)] }
+    when Symbol then tree.to_s
+    else tree
+    end
+  end
+end

data/lib/flezha/response.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "native"
+
+module Flezha
+  # One outcome of a `call`, as its Response channel delivers it: the `request`
+  # the call end sent, decoded back with the call's codec; the answer as
+  # `value`, or the `error` the call ended in (a missed deadline is
+  # `call.timeout`); `target`, the callee's instance id; and `created`, true
+  # when this call started the callee.
+  Response = Data.define(:request, :value, :error, :target, :created) do
+    def ok? = error.nil?
+
+    # The Response a controller's envelope carries, read by the core's
+    # decoder; a payload that is no envelope raises `call.malformed_response`.
+    # `decode` reads the request's and the answer's bytes.
+    def self.decode(payload, decode)
+      Core.load_extension unless defined?(Native)
+      target, created, request, value, error = Native.response_decode(payload)
+      new(
+        request: decode.call(request), value: error ? nil : decode.call(value),
+        error: error && Error.from_document(error), target:, created:
+      )
+    end
+  end
+end

data/lib/flezha/route_latest.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "codec"
+require_relative "tasklet"
+
+module Flezha
+  # The single-cell tasklet `ChannelBuilder#route_latest` expands to. Its input is
+  # what the merge's two mappings make of a value, `{ document: }` or
+  # `{ traffic: key }`; the traffic item itself never reaches it.
+  #
+  # The state is `{ document:, version:, delivered: { key => version } }` and
+  # rides the change journal like any tasklet's: `{ retain: document }`
+  # replaces the document and advances the version, and
+  # `{ delivered: key, version: }` records one key's delivery.
+  class RouteLatest < Tasklet
+    tasklet_name "route_latest"
+
+    # Version 0 is "nothing retained", so the first document lands at 1 and
+    # every key's absent entry is already behind it.
+    def init_state(_cell_key) = { document: nil, version: 0, delivered: {} }
+
+    def apply_change(state, change)
+      if change.key?(:retain)
+        state[:document] = change[:retain]
+        state[:version] += 1
+      else
+        # A Symbol, because a Hash key decodes as one: a state restored from a
+        # snapshot reads the key the live state wrote.
+        state[:delivered][change[:delivered].to_sym] = change[:version]
+      end
+    end
+
+    def run(input, ctx)
+      state = ctx.state
+      if input.key?(:document)
+        # The document is opaque: equal is the class codec's bytes, so a
+        # re-poll of an unchanged document is inert.
+        document = input[:document]
+        ctx.change({ retain: document }) unless Codec.encode(document) == Codec.encode(state[:document])
+        return nil
+      end
+
+      key = input[:traffic]
+      version = state[:version]
+      return nil if version.zero? || state[:delivered].fetch(key.to_sym, 0) >= version
+
+      # Emit first: a failed emit rides the channel's retry ladder, and
+      # recording the delivery before it would make the retry silent.
+      ctx.emit([key, state[:document]])
+      ctx.change({ delivered: key, version: version })
+      nil
+    end
+  end
+end

data/lib/flezha/runner.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "dispatch"
+require_relative "executor"
+require_relative "graph"
+require_relative "logger"
+require_relative "native"
+require_relative "relay"
+
+module Flezha
+  # The runner: what an author starts, and everything it owns while running.
+  #
+  # Classes are registered explicitly, by naming them. There is no autoload, no
+  # load-path walk and no package scan: what runs is what the author said runs,
+  # and a class that is defined but not registered never reaches the core.
+  #
+  # ## Startup order
+  #
+  #   declare classes -> warm up -> (fork, if the user forks) -> start
+  #
+  # `Process.warmup` compacts the heap and promotes the declared object graph
+  # to the old generation, which is what makes a subsequent fork
+  # copy-on-write-friendly. It runs after the last declaration and before the
+  # first `poll`. The core must NOT be started before a fork: it owns native
+  # threads that `fork(2)` does not carry, and `Core#guard!` raises naming that
+  # rule rather than letting a child serve nothing.
+  class Runner
+    attr_reader :namespace
+
+    def initialize(namespace)
+      @namespace = namespace
+      @classes = []
+      @registry = Registry.new
+      @core = nil
+      @executor = nil
+      @executor_kind = (ENV["FLEZHA_RUBY_EXECUTOR"] || "threads").to_sym
+      @executor_options = {}
+      @yjit = nil
+      @stopped = Thread::Queue.new
+      @stopping = false
+      @closing = Mutex.new
+      @teardown = []
+    end
+
+    # Register a relay class, short form or full. After start the class is
+    # declared at once: the executor serves it and the controller learns of it.
+    def register_factory(klass)
+      # A tasklet is registered by the relay that wires it.
+      unless klass.is_a?(Class) && klass < Relay
+        raise Error.new("topology.no_relay_exported", module: klass.to_s)
+      end
+
+      klass.check_declaration!
+      Graph.declare(klass.spec, @core, @registry) if @core
+      @classes << klass
+      self
+    end
+
+    # Undo a registration — the inverse of {#register_factory}, taking what it
+    # took. After start the core refuses a class with live instances on this
+    # runner; otherwise the executor stops serving it and the controller
+    # learns of it.
+    def unregister_factory(klass)
+      factory = klass.respond_to?(:factory_id) && klass.factory_id || klass.to_s
+      raise Error.new("runtime.class_not_registered", factory: factory) unless @classes.include?(klass)
+
+      if @core
+        @core.undeclare_class(factory)
+        @registry.remove(factory)
+      end
+      @classes.delete(klass)
+      self
+    end
+
+    # Which executor dispatches: `:threads` (the default) or `:fibers`.
+    def executor(kind, **options)
+      @executor_kind = kind.to_sym
+      @executor_options = options
+      self
+    end
+
+    def logger(logger)
+      Flezha.log = logger
+      self
+    end
+
+    # Administer this namespace from ordinary application code: start and stop
+    # relays, enable and disable plugins, read what is running.
+    #
+    # The controller judges every call as the identity this connection proved,
+    # so no credential is held here and nothing expires. A user grants a
+    # namespace's applications the authority once, with
+    # `flz role bind runner@<namespace> app <namespace>`; until then every call
+    # is refused.
+    def control = Control.new(@core || Core.context_free)
+
+    # Send `message` to the entry channel `channel` of `relay_id`, through
+    # the controller under the same role check as `control`, answering its
+    # verdict: `{"to" => relay, "verdict" => "delivered" | "absorbed" |
+    # "suspended"}`. `msg_id:` is stamped as `flz.msg_id`, so a relay whose
+    # input log still holds that id absorbs the repeat; `key:` reaches the
+    # partition group member whose range owns it.
+    #
+    # `local: true`: in process, without the controller: the message is on no
+    # disk, is lost if the runner stops before handling it, and a relay's
+    # input log does not cover it. It answers `nil`.
+    #
+    # Named `send_to` because `send` is every Ruby object's own.
+    def send_to(relay_id, message, channel, msg_id: nil, key: nil, local: false)
+      JSON.parse((@core || Core.context_free).send_message(relay_id, channel, message.b, msg_id, key, local))
+    end
+
+    # Call the entry channel `channel` of `relay_id` with `value`, through the
+    # controller under the same role check as `send_to`, answering what the
+    # relay answers: a JSON value, a String for text, binary bytes for the
+    # binary formats, or `{"accepted" => true}` from a channel no output
+    # answers. `value` is encoded as an output naming no codec encodes it.
+    def call(relay_id, channel, value)
+      payload = [Codec.plain_payload(value, "a call to '#{relay_id}'")].pack("m0")
+      args = JSON.generate([relay_id, channel, payload, { "payload" => "base64" }])
+      reply = JSON.parse((@core || Core.context_free).admin_call("Relay.call_channel", args))
+      return { "accepted" => true } if reply["accepted"]
+
+      %w[json text].include?(reply["answer_codec"]) ? reply["answer"] : reply["answer"].unpack1("m0")
+    end
+
+    # The ids of the relay instances bound on this runner now, read without
+    # the controller. Refused with `runtime.runner_not_started` before `boot`.
+    def relays = (@core || raise(Error.new("runtime.runner_not_started"))).relays
+
+    # Override the YJIT decision. `nil` (the default) means "decide", `false`
+    # means "leave it off".
+    def yjit(enabled)
+      @yjit = enabled
+      self
+    end
+
+    # Declare, warm up, connect and start serving — everything up to and
+    # including the first poll, and nothing that blocks.
+    #
+    # Separate from `run` so a host with its own supervision tree can own the
+    # waiting, and so the startup ORDER is a thing a test can observe rather
+    # than a comment.
+    def start(core: nil)
+      jit = resolve_yjit
+
+      # Before anything else: a native library built against a different
+      # activation schema is refused here, with no controller connection
+      # attempted.
+      @core = core || Core.create
+
+      declare_all
+      # After the last declaration and before the first poll.
+      Process.warmup
+
+      # The core's termination handler also runs the handler installed before
+      # it. Ruby's default raises in the main thread and ends the process before
+      # any state is shipped, so it gives way to the system default, which is
+      # never run; a trap the application set is kept.
+      %w[TERM INT].each do |signal|
+        previous = Signal.trap(signal, "SYSTEM_DEFAULT")
+        Signal.trap(signal, previous) unless previous == "DEFAULT"
+      end
+      begin
+        @core.start(@namespace)
+      rescue StandardError
+        # The core holds what it said while connecting until a take; no
+        # supervisor is left to take it.
+        Flezha.log_notices(@core.take_notices)
+        raise
+      end
+      observe_shutdown
+
+      @executor = build_executor
+      @executor.start
+
+      Flezha.log.info(
+        "runner up on namespace #{@namespace}: #{@executor.name} executor, " \
+        "#{@executor.size} workers, yjit #{jit}"
+      )
+      self
+    end
+
+    # Declare, warm up, connect and serve until shutdown: `start`, then
+    # `await_termination`.
+    def run(core: nil)
+      start(core: core)
+      await_termination
+    end
+
+    # Wait for shutdown, then close. A host that called `start` can work
+    # between the two, making control calls for one, and still stop the way
+    # `run` does.
+    def await_termination
+      @stopped.pop
+      close
+      self
+    end
+
+    # Stop fetching, drain what is in flight, release the core and wake every
+    # thread in `await_termination`. Idempotent: the waiter it wakes finds the
+    # core already released. Not for a trap handler, since it takes a lock.
+    def close
+      @closing.synchronize { release_core }
+      stop
+      nil
+    end
+
+    private
+
+    # Wakes `await_termination`. Trap-safe: a queue push and no lock.
+    def stop
+      return if @stopping
+
+      @stopping = true
+      @stopped.push(:stop)
+    end
+
+    def release_core
+      return unless @core
+
+      Flezha.log.info("draining")
+      @core.shutdown
+      undrained = @executor ? @executor.stop : 0
+      @teardown.each(&:call)
+      @teardown.clear
+      # The context is released only when nothing is still running against it.
+      # A worker the bounded drain gave up on is inside user code and may yet
+      # call the core; freeing the context under it would be a use-after-free
+      # in native code. The process is on its way out either way, so the
+      # kernel reclaims what this skips.
+      @core.free if undrained.zero?
+      @core = nil
+    end
+
+    def declare_all
+      # The verdict before the registration: the core judges the record and
+      # this SDK renders it, so an author meets a declaration refusal rather
+      # than a native failure at the first connection.
+      @classes.each { |klass| Graph.declare(klass.spec, @core, @registry) }
+      raise Error.new("runtime.no_relays") if @registry.empty?
+    end
+
+    def build_executor
+      deps = DispatchDeps.new(registry: @registry, bridge: @core)
+      case @executor_kind
+      when :threads then ThreadExecutor.new(@core, deps, **@executor_options)
+      when :fibers then FiberExecutor.new(@core, deps, **@executor_options)
+      else
+        raise Error.new("usage.unknown_word", noun: "executor", value: @executor_kind.to_s,
+                                              allowed: %w[threads fibers])
+      end
+    end
+
+    # Shutdown is observed three ways, because the harness, a user and the
+    # controller each have their own: end of file on standard input, a signal,
+    # and the core's own stop — which every worker sees as `:shutting_down`
+    # from its next poll.
+    #
+    # The first two are the core's, on a thread that holds no GVL and no Ruby
+    # object: it installs the SIGINT and SIGTERM handler when the runner starts,
+    # and the watch below is the same exit by another name. The harness manages
+    # a runner as an Erlang Port and stops it by closing the port, which is this
+    # process's standard input.
+    def observe_shutdown
+      @core.watch_stdin_eof unless $stdin.tty?
+    end
+
+    # YJIT is on by default because handler bodies are the one thing the GVL
+    # bounds, so the JIT's gain lands exactly where the ceiling is. The
+    # user's decision wins, and the resulting state is reported in the
+    # startup line so a measurement can never be ambiguous about it.
+    def resolve_yjit
+      return "disabled (runner override)" if @yjit == false
+      return "unavailable (this Ruby was built without it)" unless defined?(RubyVM::YJIT)
+      return "enabled (already on)" if RubyVM::YJIT.enabled?
+      return "disabled (RUBY_YJIT_ENABLE set)" if ENV.key?("RUBY_YJIT_ENABLE")
+      return "disabled (FLEZHA_YJIT=0)" if ENV["FLEZHA_YJIT"] == "0"
+
+      RubyVM::YJIT.enable
+      RubyVM::YJIT.enabled? ? "enabled" : "unavailable (enable refused)"
+    end
+  end
+
+  # Start here: `Flezha.create_runner("default").register_factory(MyRelay).run`.
+  def self.create_runner(namespace) = Runner.new(namespace)
+end