gienah 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0b5ddd667daab9746e62685ac6aa5c2815423723dfb32edad31f0ccd884d7f1
+  data.tar.gz: bed2f863f325ef4ccd850e4c8e1a1b012a2bb865ff287abd61f34d4a0dd02e71
+SHA512:
+  metadata.gz: a07f343f8c19bceae8d046574b458ff1df2a86831cee69e671ee4c784af5f4ce3e10bc7887028ccdc9903432a05f878be1a89712a87c99d3768bc3cc19a08385
+  data.tar.gz: a28009e92874f177dff8cfb14dab1138efb8d983cb1d4a72307769802f90c861bf41ca8fdca87ee235364a163a2e3f7bb8449cb05b7adfcbba7ecfbc9daecb10

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-19
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# Gienah
+
+Gienah (γ Corvi) is an IAU-approved star name derived from Arabic *al-janāḥ*,
+“the wing”. It is a small, Canopus-independent host for out-of-process Ruby
+plugins.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add gienah
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install gienah
+```
+
+## Usage
+
+A host registers application-specific methods and activates a manifest only
+when its activation reason occurs:
+
+```ruby
+require "gienah"
+
+host = Gienah::Host.new(api_version: 1)
+host.expose("workspace/notify") { |params| puts params.fetch("message") }
+host.discover(["plugins"])
+instance = host.activate("example", reason: "onStartup")
+instance&.call("refresh", {}).await(timeout: 2)
+```
+
+Plugin entrypoints use the SDK:
+
+```ruby
+require "gienah"
+Gienah::Plugin.export("refresh") { {"ok" => true} }
+Gienah::Plugin.run
+```
+
+`gienah` treats capabilities as opaque strings, but rejects unknown manifest
+capabilities and denies host methods until the declared capability is granted.
+Dangerous filesystem, network, and process capabilities require `saiph`.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/noxdea/gienah.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/adr/000-template.md

@@ -0,0 +1,17 @@
+# ADR-000: Template
+
+## Status
+
+Accepted
+
+## Context
+
+Use this template for a decision that affects the public host or plugin protocol.
+
+## Decision
+
+Describe the decision.
+
+## Consequences
+
+Describe the trade-offs.

data/docs/adr/README.md

@@ -0,0 +1,3 @@
+# Architecture decisions
+
+Gienah records protocol and lifecycle decisions here.

data/index.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="theme-color" content="#060a13">
+  <meta name="description" content="Gienah is an out-of-process Ruby plugin host with capability gates.">
+  <title>Gienah — An out-of-process plugin host for Ruby</title>
+  <link rel="stylesheet" href="site.css">
+</head>
+<body style="--accent:#e5adf2">
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header class="site-header">
+    <a class="brand" href="#"><span class="star-mark"></span>Gienah</a>
+    <nav aria-label="Primary navigation"><a href="#features">Capabilities</a><a href="#install">Install</a><a href="https://github.com/noxdea/gienah">GitHub</a></nav>
+  </header>
+  <main id="main">
+    <section class="hero">
+      <div>
+        <p class="constellation">γ Corvi · plugin host</p>
+        <h1>Keep plugins at arm’s length.</h1>
+        <p class="lede">A small out-of-process Ruby plugin host with framed RPC, activation lifecycle, capability gates, and a focused plugin SDK.</p>
+        <div class="actions"><a class="button primary" href="#install">Install Gienah</a><a class="button" href="https://github.com/noxdea/gienah">View source</a></div>
+        <ul class="facts"><li><strong>Out of process</strong></li><li>Ruby ≥ 3.1</li><li>MIT licensed</li></ul>
+      </div>
+      <div class="instrument" aria-label="Plugin host activation example">
+        <div class="instrument-head"><span>host / example plugin</span><span class="signal">active</span></div>
+        <div class="instrument-body">
+          <div class="diagram">
+            <span class="orbit" aria-hidden="true"></span>
+            <div class="node nw"><strong>Manifest</strong>api 1<br>onStartup</div>
+            <div class="node ne"><strong>RPC</strong>Content-Length<br>framed</div>
+            <div class="node core"><strong>Gienah host</strong>plugin example<br>pid 9134</div>
+            <div class="node sw"><strong>Capability</strong>workspace.notify<br>granted</div>
+            <div class="node se"><strong>Sandbox</strong>saiph<br>required</div>
+          </div>
+        </div>
+      </div>
+    </section>
+    <section class="features" id="features">
+      <div class="section-heading"><h2>A smaller blast radius.</h2><p>Gienah keeps extension code outside the host process and checks declared capabilities before a plugin can call application methods.</p></div>
+      <div class="feature-grid">
+        <article><h3>Process isolation</h3><p>Run plugin entrypoints as child processes connected through bounded framed messages.</p></article>
+        <article><h3>Capability gates</h3><p>Reject unknown declarations and deny host methods until the matching capability is granted.</p></article>
+        <article><h3>Lifecycle control</h3><p>Discover manifests, activate on a named reason, make timeout-aware calls, and shut down cleanly.</p></article>
+      </div>
+    </section>
+    <section class="install" id="install">
+      <div class="install-copy"><h2>Host a plugin.</h2><p>Expose only application-specific methods, then activate manifests when their reason occurs.</p></div>
+      <div class="terminal"><div class="terminal-bar">Ruby</div><pre><span class="prompt">$</span> bundle add gienah
+
+host = Gienah::Host.new(api_version: 1)
+host.expose("workspace/notify") { |params|
+  puts params.fetch("message")
+}
+host.discover(["plugins"])
+host.activate("example", reason: "onStartup")</pre></div>
+    </section>
+  </main>
+  <footer><p>Gienah · Pure Ruby · MIT</p><div><a href="https://rubygems.org/gems/gienah">RubyGems</a><a href="https://github.com/noxdea/gienah">GitHub</a></div></footer>
+</body>
+</html>

data/lib/gienah/future.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Gienah
+  class Future
+    def initialize(id, on_cancel: nil)
+      @id = id
+      @on_cancel = on_cancel
+      @lock = Mutex.new
+      @ready = ConditionVariable.new
+      @callbacks = []
+    end
+
+    attr_reader :id
+
+    def fulfill(value = nil, error: nil)
+      callbacks = @lock.synchronize do
+        return self if @done
+        @value = value
+        @error = error
+        @done = true
+        @ready.broadcast
+        callbacks, @callbacks = @callbacks, []
+        callbacks
+      end
+      callbacks.each { |callback| callback.call(@value, @error) }
+      self
+    end
+
+    def await(timeout: nil)
+      validate_timeout(timeout)
+      deadline = timeout && Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      timed_out = false
+      result = @lock.synchronize do
+        until @done
+          remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining && remaining <= 0
+            timed_out = true
+            break
+          end
+          @ready.wait(@lock, remaining)
+        end
+        break if timed_out
+        raise @error if @error
+        @value
+      end
+      if timed_out
+        cancel
+        raise Gienah::Timeout, "request #{@id} timed out"
+      end
+      result
+    end
+
+    def then(&callback)
+      raise ArgumentError, "callback required" unless callback
+      ready = @lock.synchronize do
+        @callbacks << callback unless @done
+        @done
+      end
+      callback.call(@value, @error) if ready
+      self
+    end
+
+    def cancel
+      callback = @lock.synchronize do
+        return false if @done || @cancelling
+        @cancelling = true
+        @on_cancel
+      end
+      begin
+        callback&.call(@id)
+      rescue StandardError
+        nil
+      end
+      fulfill(error: Error.new("request #{@id} cancelled"))
+      true
+    end
+
+    def done?
+      @lock.synchronize { !!@done }
+    end
+
+    private
+
+    def validate_timeout(timeout)
+      return if timeout.nil? || (timeout.is_a?(Numeric) && timeout.finite? && timeout >= 0)
+      raise ArgumentError, "timeout must be finite and nonnegative"
+    end
+  end
+end

data/lib/gienah/host.rb

@@ -0,0 +1,395 @@
+# frozen_string_literal: true
+
+module Gienah
+  class Host
+    Definition = Value.define(:method, :capability, :handler)
+    DEFAULT_RESTART = {attempts: 3, window: 60, backoff: [1, 5, 30]}.freeze
+
+    attr_reader :api_version
+
+    def initialize(api_version:, dispatch: nil, sandbox: true, restart: {}, limits: {}, transport_factory: nil)
+      raise ArgumentError, "api_version must be positive" unless api_version.is_a?(Integer) && api_version.positive?
+
+      @api_version = api_version
+      @dispatch = dispatch
+      @sandbox = sandbox
+      @restart = restart || {}
+      @limits = limits || {}
+      @transport_factory = transport_factory
+      @manifests = {}
+      @instances = {}
+      @definitions = {}
+      @contribution_handlers = []
+      @error_handlers = []
+      @lock = Mutex.new
+      @restart_history = Hash.new { |hash, key| hash[key] = [] }
+      @disabled = {}
+      @shutting_down = false
+    end
+
+    def expose(method, capability: nil, &handler)
+      raise ArgumentError, "method must be a nonempty String" unless method.is_a?(String) && !method.empty?
+      raise ArgumentError, "handler required" unless handler
+      raise ArgumentError, "capability must be a String" unless capability.nil? || capability.is_a?(String)
+
+      @definitions[method] = Definition.new(method, capability, handler)
+      self
+    end
+
+    def discover(directories)
+      manifests = Array(directories).flat_map do |directory|
+        path = File.expand_path(directory.to_s)
+        candidates = if File.file?(path)
+          [path]
+        else
+          Dir[File.join(path, "**", "plugin.{json,jsonc}")]
+        end
+        candidates.sort.map { |manifest| Manifest.load(manifest) }
+      end
+      manifests.each { |manifest| add(manifest) }
+      manifests
+    end
+
+    def add(manifest)
+      raise ArgumentError, "expected Gienah::Manifest" unless manifest.is_a?(Manifest)
+      raise LifecycleError, "unsupported plugin api version #{manifest.api_version}" unless manifest.api_version == @api_version
+
+      @lock.synchronize do
+        @manifests[manifest.id] = manifest
+        @disabled.delete(manifest.id)
+      end
+      @contribution_handlers.each { |handler| handler.call(manifest.id, manifest.contributes) }
+      manifest
+    end
+
+    def activate(id, reason:)
+      manifest = @lock.synchronize { @manifests.fetch(id.to_s) { raise ArgumentError, "unknown plugin: #{id}" } }
+      raise LifecycleError, "plugin #{id} is disabled" if @lock.synchronize { @disabled.key?(id.to_s) }
+      return @instances[id.to_s] if @instances.key?(id.to_s)
+      return nil unless activation_matches?(manifest.activation, reason.to_s)
+
+      instance = Instance.new(self, manifest)
+      @lock.synchronize { @instances[manifest.id] = instance }
+      begin
+        instance.start
+      rescue StandardError
+        @lock.synchronize { @instances.delete(manifest.id) }
+        raise
+      end
+      instance
+    end
+
+    def deactivate(id)
+      instance = @lock.synchronize { @instances.delete(id.to_s) }
+      instance&.shutdown
+    end
+
+    def instances
+      @lock.synchronize { @instances.values.dup }
+    end
+
+    def disabled?(id)
+      @lock.synchronize { @disabled.key?(id.to_s) }
+    end
+
+    def on_contribution(&block)
+      raise ArgumentError, "callback required" unless block
+
+      @contribution_handlers << block
+      self
+    end
+
+    def on_error(&block)
+      raise ArgumentError, "callback required" unless block
+
+      @error_handlers << block
+      self
+    end
+
+    def shutdown
+      @shutting_down = true
+      instances.each(&:shutdown)
+      @lock.synchronize { @instances.clear }
+      nil
+    end
+
+    def dispatch_request(instance, message)
+      method = message["method"]
+      definition = @definitions[method]
+      unless definition
+        return Protocol.response(message["id"], error: {"code" => -32601, "message" => "method not found: #{method}"})
+      end
+      if definition.capability && !instance.granted?(definition.capability)
+        return Protocol.response(message["id"], error: {"code" => -32001, "message" => "capability denied: #{definition.capability}"})
+      end
+
+      params = message.fetch("params", {})
+      result = if definition.handler.arity == 1
+        definition.handler.call(params)
+      else
+        definition.handler.call(instance, params)
+      end
+      Protocol.response(message["id"], result: result)
+    rescue CapabilityDenied => error
+      Protocol.response(message["id"], error: {"code" => -32001, "message" => error.message})
+    rescue StandardError => error
+      report_error(error, instance)
+      Protocol.response(message["id"], error: {"code" => -32000, "message" => "#{error.class}: #{error.message}"})
+    end
+
+    def dispatch_notification(instance, message)
+      @dispatch&.call(instance, message["method"], message.fetch("params", {}))
+    rescue StandardError => error
+      report_error(error, instance)
+    end
+
+    def report_error(error, instance = nil)
+      @error_handlers.each { |handler| handler.call(error, instance) }
+    rescue StandardError
+      nil
+    end
+
+    def instance_failed(instance, error)
+      report_error(error, instance)
+      config = DEFAULT_RESTART.merge(@restart.transform_keys(&:to_sym))
+      attempts = config.fetch(:attempts).to_i
+      return if attempts <= 0 || @shutting_down
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      history = @lock.synchronize do
+        next unless @instances[instance.id].equal?(instance)
+
+        @restart_history[instance.id].reject! { |started| now - started >= config.fetch(:window).to_f }
+        if @restart_history[instance.id].length < attempts
+          @restart_history[instance.id] << now
+        else
+          nil
+        end
+      end
+      unless history
+        @lock.synchronize { @disabled[instance.id] = true }
+        report_error(LifecycleError.new("plugin #{instance.id} disabled after repeated failures"), instance)
+        return
+      end
+
+      index = history.length - 1
+      backoff = Array(config.fetch(:backoff))
+      delay = backoff[index] || backoff.last || 0
+      Thread.new do
+        sleep(delay.to_f) if delay.to_f.positive?
+        next unless @lock.synchronize { !@shutting_down && @instances[instance.id].equal?(instance) && instance.state == :failed }
+
+        instance.restart
+      rescue StandardError => restart_error
+        report_error(restart_error, instance)
+      end
+    end
+
+    def transport_for(instance, &receive)
+      if @transport_factory
+        @transport_factory.call(instance.manifest, &receive)
+      else
+        Sandbox.ensure_safe!(instance.manifest.capabilities) if @sandbox
+        entry = File.expand_path(instance.manifest.entry, instance.manifest.root)
+        raise Error, "plugin entry does not exist: #{entry}" unless File.file?(entry)
+        command = [RbConfig.ruby, "-I", File.expand_path("..", __dir__), entry]
+        policy = @sandbox && Sandbox.available? ? Sandbox.policy_for(instance.manifest.capabilities, root: instance.manifest.root) : nil
+        Transport.open(command, cwd: instance.manifest.root, env: {}, policy: policy, &receive)
+      end
+    end
+
+    def request_timeout(manifest)
+      value = manifest.limits.fetch("request_timeout_ms", @limits.fetch(:request_timeout_ms, 2_000))
+      value.to_f / 1_000
+    end
+
+    private
+
+    def activation_matches?(patterns, reason)
+      patterns.empty? || patterns.any? do |pattern|
+        pattern == reason || (pattern.end_with?("*") && reason.start_with?(pattern.delete_suffix("*")))
+      end
+    end
+  end
+
+  class Instance
+    STATES = %i[inactive starting ready stopping failed].freeze
+
+    attr_reader :id, :manifest, :state
+
+    def initialize(host, manifest)
+      @host = host
+      @manifest = manifest
+      @id = manifest.id
+      @state = :inactive
+      @lock = Mutex.new
+      @pending = {}
+      @next_id = 0
+    end
+
+    def start
+      transition(:starting, from: :inactive)
+      @transport = @host.transport_for(self) { |message, error| receive(message, error) }
+      startup_timeout = @manifest.limits.fetch("startup_timeout_ms", 5_000).to_f / 1_000
+      response = request("initialize", {
+        "api_version" => @host.api_version,
+        "capabilities" => @manifest.capabilities,
+        "host" => {"name" => "gienah", "version" => Gienah::VERSION}
+      }, timeout: startup_timeout).await(timeout: startup_timeout)
+      raise LifecycleError, "plugin initialization failed" unless response.is_a?(Hash)
+
+      transition(:ready, from: :starting)
+      notify("initialized", {"api_version" => @host.api_version})
+      self
+    rescue StandardError => error
+      @lock.synchronize { @state = :failed }
+      @host.report_error(error, self)
+      close_transport
+      raise
+    end
+
+    def call(method, params = {}, timeout: nil)
+      ensure_ready!
+      request(method, params, timeout: timeout)
+    end
+
+    def notify(method, params = {})
+      ensure_ready!
+      @transport.write(Protocol.notification(method, params), max_size: max_message_size)
+      nil
+    end
+
+    def granted?(capability)
+      requested = capability.to_s
+      return true if @manifest.capabilities.include?(requested)
+
+      # Reserved host-pattern capabilities are intentionally matched here so
+      # applications can expose one generic method and still keep the gate
+      # fail-closed for every other host.
+      if requested.start_with?("net:")
+        host = requested.delete_prefix("net:")
+        return @manifest.capabilities.any? do |entry|
+          next false unless entry.start_with?("net:")
+
+          pattern = entry.delete_prefix("net:")
+          File.fnmatch?(pattern, host, File::FNM_DOTMATCH)
+        end
+      end
+      false
+    end
+
+    def kill
+      @lock.synchronize { @state = :inactive }
+      fail_pending(Error.new("plugin terminated"))
+      close_transport
+      nil
+    end
+
+    def restart
+      @lock.synchronize { @state = :inactive if @state == :failed }
+      start
+    end
+
+    def shutdown
+      current = @lock.synchronize { @state }
+      return if current == :inactive
+
+      if current == :ready
+        @lock.synchronize { @state = :stopping }
+        begin
+          request("shutdown", {}).await(timeout: 0.5)
+        rescue StandardError
+          nil
+        end
+      end
+      kill
+    end
+
+    private
+
+    def request(method, params, timeout: nil)
+      id = @lock.synchronize do
+        @next_id += 1
+        @next_id
+      end
+      future = Future.new(id, on_cancel: ->(request_id) {
+        @transport&.write(Protocol.notification("$/cancel", {"id" => request_id}), max_size: max_message_size)
+      })
+      @lock.synchronize { @pending[id] = future }
+      deadline = timeout || @host.request_timeout(@manifest)
+      unless deadline.is_a?(Numeric) && deadline.finite? && deadline.positive?
+        @lock.synchronize { @pending.delete(id) }
+        raise ArgumentError, "timeout must be finite and positive"
+      end
+      timer = Thread.new do
+        sleep(deadline)
+        next if future.done?
+
+        begin
+          @transport&.write(Protocol.notification("$/cancel", {"id" => id}), max_size: max_message_size)
+        rescue StandardError
+          nil
+        end
+        future.fulfill(error: Timeout.new("request #{id} timed out"))
+      end
+      timer.report_on_exception = false
+      future.then { |_value, _error| timer.kill if timer.alive? && timer != Thread.current }
+      begin
+        @transport.write(Protocol.request(id, method, params), max_size: max_message_size)
+      rescue StandardError => error
+        @lock.synchronize { @pending.delete(id) }
+        future.fulfill(error: error)
+      end
+      future
+    end
+
+    def receive(message, error)
+      if error
+        @lock.synchronize { @state = :failed unless %i[inactive stopping].include?(@state) }
+        fail_pending(error)
+        @host.instance_failed(self, error)
+        return
+      end
+      return unless message
+      if message.key?("method")
+        response = if message.key?("id")
+          @host.dispatch_request(self, message)
+        else
+          @host.dispatch_notification(self, message)
+          nil
+        end
+        @transport.write(response, max_size: max_message_size) if response
+      else
+        future = @lock.synchronize { @pending.delete(message["id"]) }
+        return unless future
+        message.key?("error") ? future.fulfill(error: Error.new(message["error"]["message"].to_s)) : future.fulfill(message["result"])
+      end
+    rescue StandardError => dispatch_error
+      @host.report_error(dispatch_error, self)
+    end
+
+    def ensure_ready!
+      raise LifecycleError, "plugin #{@id} is #{@state}" unless @lock.synchronize { @state == :ready }
+    end
+
+    def transition(target, from:)
+      @lock.synchronize do
+        raise LifecycleError, "cannot transition #{@state} to #{target}" unless @state == from
+        @state = target
+      end
+    end
+
+    def fail_pending(error)
+      futures = @lock.synchronize { pending, @pending = @pending.values, {}; pending }
+      futures.each { |future| future.fulfill(error: error) }
+    end
+
+    def close_transport
+      @transport&.close
+      @transport = nil
+    end
+
+    def max_message_size
+      @manifest.limits.fetch("max_message_bytes", Protocol::MAX_MESSAGE)
+    end
+  end
+end