exots 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7ccbf2566f4dd5ff3c05e550df972b800bd465b383bbd6464dbed34206a7a0a
+  data.tar.gz: 2e9e5bcb9e60c831de10e5c789fe285081938cc020a57d5f1fafef60f3e6deeb
+SHA512:
+  metadata.gz: 2e672b26d285707b81cf8c6bf420547a46834438cdef1e7b9f67ab072cfa1d3a72e879d1a42c4a1f14493af92e6a74c57241cef4588f1fd23926a4cd2cdcdd9a
+  data.tar.gz: df569b4df17b4787063bbfa694939eaf606cc39f3efc166f9a8e9aafb707e75a897e86b118417fc7f55df50ae414a04dfbffdb8cebdd36b5d422f881280d5d58

data/AGENTS.md

@@ -0,0 +1,21 @@
+# gem/AGENTS.md
+
+This directory contains the **Ruby Client** implementation for Exots.
+
+## Tech Stack
+- **Language:** Ruby
+- **Package Manager:** `bundler`
+- **Testing:** `rspec`
+
+## Key Commands
+- **Install:** `bundle install`
+- **Test:** `bundle exec rspec`
+- **Pack:** `bundle exec rake pack` (Automatically includes root `LICENSE` and `README.md`)
+
+## Development Workflow
+1.  Make changes to the Ruby code in `lib/`.
+2.  Run tests: `bundle exec rspec`.
+3.  If adding new dependencies, update `exots.gemspec` and run `bundle install`.
+4.  To release/distribute, run `bundle exec rake pack`.
+
+Note: Do not manually edit `gem/LICENSE` or `gem/README.md`. These are automatically copied from the project root during the build process.

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, sunteya
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,80 @@
+# Exots
+
+**Exots** (Exo-Typescript) is a high-performance Inter-Process Communication (IPC) bridge designed to allow Ruby applications to seamlessly invoke functions written in TypeScript/JavaScript.
+
+It acts as a **process manager** that spawns a Node.js (or Bun/Deno) runtime and communicates via **JSON-RPC 2.0** over **HTTP** on **Unix Domain Sockets (UDS)**. This approach ensures high performance and security by avoiding local TCP ports and leveraging file-system-level access control.
+
+## Architecture
+
+The system operates on a Host/Plugin model:
+
+1.  **Host (Ruby)**: The `exots` gem manages the lifecycle of the JavaScript process. It creates a temporary communication socket and injects its path into the child process.
+2.  **Plugin (TypeScript/Node.js)**: The `exots` npm package wraps your functions and exposes them via an HTTP server listening on the injected socket path.
+
+## Components
+
+### NPM Package (`exots`)
+-   **Role**: RPC Server
+-   **Transport**: HTTP over Unix Domain Socket
+-   **Protocol**: JSON-RPC 2.0
+-   **Configuration**: Accepts a map of functions and listens on a socket path provided via environment variables.
+
+### Ruby Gem (`exots`)
+-   **Role**: Process Manager & RPC Client
+-   **Features**:
+    -   Spawns and manages the Node.js/Bun process.
+    -   Automatic socket path generation and handshake.
+    -   Zero-dependency HTTP client over Unix Sockets.
+    -   Maps JSON-RPC errors to Ruby exceptions.
+
+## Usage Example
+
+### 1. TypeScript Side (`plugin.js`)
+Create a script that exports your functions.
+
+```javascript
+import { Server } from 'exots'
+
+// 1. Initialize the server with exposed functions
+const server = new Server({
+  add: ({ a, b }) => a + b,
+  render: async ({ title }) => {
+    // Perform complex operations, e.g., SSR
+    return `<div>${title}</div>`
+  }
+})
+
+// 2. Start the server (automatically handles arguments and environment variables)
+server.run(process.argv)
+```
+
+### 2. Ruby Side
+Use the client to spawn the process and call functions.
+
+```ruby
+require 'exots'
+
+# 1. Initialize the client
+client = Exots::Client.new(
+  script_path: "plugin.js",
+  socket_path: Rails.root.join("tmp/sockets/exots.sock")
+)
+
+begin
+  # 2. Start the process and connect
+  context = client.start
+
+  # 3. Call functions transparently
+  sum = context.call("add", a: 5, b: 3)
+  puts "Sum: #{sum}" 
+  # => Sum: 8
+
+  html = context.call("render", title: "Hello World")
+  puts "HTML: #{html}"
+  # => HTML: <div>Hello World</div>
+
+ensure
+  # 4. Clean shutdown
+  client.stop
+end
+```

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+
+task :pack => :build
+
+task :build => :copy_assets
+
+task :copy_assets do
+  FileUtils.cp "../LICENSE", "."
+  FileUtils.cp "../README.md", "."
+end
+
+task :clean_assets do
+  FileUtils.rm ["LICENSE", "README.md"], force: true
+end
+
+# Ensure cleanup happens even if build fails, or explicitly call clean_assets
+# For now, let's just make build depend on copy. Users can run `git clean -fdx` or similar if they want super clean,
+# but we also added them to .gitignore so they won't pollute git status.

data/lib/exots/client.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'tmpdir'
+require 'fileutils'
+require 'timeout'
+
+module Exots
+  class Client
+    attr_reader :pid, :socket_path, :pid_path
+
+    def initialize(script_path:, socket_path:, pid_path: nil, runner: Runner::Node, timeout: 5.0, auto_stop: true)
+      @script_path = script_path
+      @socket_path = socket_path
+      @pid_path = pid_path
+      @runner = runner
+      @timeout = timeout
+      @running = false
+      @context = nil
+      @owner = false
+      @owner_pid = nil
+
+      at_exit { stop } if auto_stop
+    end
+
+    def call(method, params = {})
+      start unless @running
+      @context.call(method, params)
+    end
+
+    def start
+      return @context if @running
+
+      lock_path = "#{@socket_path}.lock"
+      # Ensure lock directory exists
+      FileUtils.mkdir_p(File.dirname(lock_path))
+
+      File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |f|
+        f.flock(File::LOCK_EX)
+
+        if server_alive?
+          @running = true
+          @owner = false
+        else
+          File.unlink(@socket_path) if File.exist?(@socket_path)
+          spawn_process
+          wait_for_socket
+          @running = true
+          @owner = true
+          @owner_pid = Process.pid
+        end
+      end
+
+      @context = Context.new(@socket_path)
+    end
+
+    def stop
+      if @owner && @pid && Process.pid == @owner_pid && process_running?
+        Process.kill('TERM', @pid)
+        begin
+          Timeout.timeout(2) { Process.wait(@pid) }
+        rescue Timeout::Error
+          Process.kill('KILL', @pid)
+          Process.wait(@pid)
+        rescue Errno::ECHILD
+          # Already gone
+        end
+      end
+    rescue Errno::ESRCH
+      # Process already gone
+    ensure
+      if @owner && Process.pid == @owner_pid
+        cleanup_files
+        File.unlink("#{@socket_path}.lock") if File.exist?("#{@socket_path}.lock")
+      end
+      @running = false
+      @pid = nil
+      @context = nil
+      @owner = false
+      @owner_pid = nil
+    end
+
+    private
+
+    def server_alive?
+      return false unless File.exist?(@socket_path)
+
+      begin
+        UNIXSocket.new(@socket_path).close
+        true
+      rescue Errno::ECONNREFUSED, Errno::ENOENT
+        false
+      end
+    end
+
+    def spawn_process
+      env = {
+        'EXOTS_SOCKET' => @socket_path
+      }
+      env['EXOTS_PID'] = @pid_path if @pid_path
+
+      # Use exec form to avoid shell overhead
+      args = @runner.command(@script_path, @socket_path, @pid_path)
+      @pid = Process.spawn(env, *args)
+    end
+
+    def wait_for_socket
+      start_time = Time.now
+
+      until server_alive?
+        raise ProcessError, "Timeout waiting for socket at #{@socket_path}" if Time.now - start_time > @timeout
+
+        unless process_running?
+          # Try to read stderr/stdout if we could, but for now just report exit
+          raise ProcessError, 'Process exited unexpectedly'
+        end
+
+        sleep 0.1
+      end
+    end
+
+    def process_running?
+      return false unless @pid
+
+      Process.getpgid(@pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def cleanup_files
+      # FileUtils.rm_rf(@tmp_dir) if @tmp_dir && File.directory?(@tmp_dir)
+    end
+  end
+end

data/lib/exots/context.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'json'
+require 'securerandom'
+
+module Exots
+  class Context
+    attr_reader :socket_path
+
+    def initialize(socket_path)
+      @socket_path = socket_path
+    end
+
+    def call(method, *args)
+      id = SecureRandom.uuid
+
+      payload = {
+        jsonrpc: '2.0',
+        method: method,
+        params: args,
+        id: id
+      }
+
+      response = send_request(payload)
+      handle_response(response, id)
+    end
+
+    private
+
+    def send_request(payload)
+      body = JSON.generate(payload)
+
+      UNIXSocket.open(@socket_path) do |sock|
+        sock.write("POST / HTTP/1.1\r\n")
+        sock.write("Host: localhost\r\n")
+        sock.write("Content-Type: application/json\r\n")
+        sock.write("Content-Length: #{body.bytesize}\r\n")
+        sock.write("\r\n")
+        sock.write(body)
+
+        parse_response(sock)
+      end
+    rescue Errno::ENOENT, Errno::ECONNREFUSED
+      raise Error, "Failed to connect to socket at #{@socket_path}"
+    end
+
+    def parse_response(sock)
+      status_line = sock.gets
+      return nil unless status_line
+
+      status = status_line.split(' ')[1].to_i
+      headers = {}
+
+      while (line = sock.gets) && line != "\r\n"
+        key, value = line.split(':', 2)
+        headers[key.strip.downcase] = value.strip if key
+      end
+
+      if status == 204
+        return { 'result' => nil } # Notification or empty response
+      end
+
+      raise Error, "HTTP Error: #{status}" unless status >= 200 && status < 300
+
+      content_length = headers['content-length']&.to_i
+      return nil unless content_length && content_length > 0
+
+      body = sock.read(content_length)
+      JSON.parse(body)
+    end
+
+    def handle_response(response, _id)
+      return nil if response.nil?
+
+      if response.key?('error')
+        error = response['error']
+        raise RPCError, "#{error['message']} (code: #{error['code']})"
+      end
+
+      response['result']
+    end
+  end
+end

data/lib/exots/runner.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Exots
+  class Runner
+    attr_reader :bin, :args
+
+    def initialize(bin, args: [])
+      @bin = bin
+      @args = args
+    end
+
+    def command(script, socket_path, pid_path = nil)
+      cmd_args = [@bin] + @args + [script, '--socket', socket_path]
+      cmd_args += ['--pid', pid_path] if pid_path
+      cmd_args
+    end
+
+    Node = new('node')
+    Bun = new('bun')
+  end
+end

data/lib/exots/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Exots
+  VERSION = '0.1.0'
+end

data/lib/exots.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'exots/version'
+require_relative 'exots/runner'
+require_relative 'exots/client'
+require_relative 'exots/context'
+
+module Exots
+  class Error < StandardError; end
+  class ProcessError < Error; end
+  class RPCError < Error; end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: exots
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- sunteya
+bindir: exe
+cert_chain: []
+date: 2026-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Exots provides a seamless bridge to spawn Node.js/Bun processes and execute
+  functions via high-performance Unix Domain Sockets.
+email:
+- sunteya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/exots.rb
+- lib/exots/client.rb
+- lib/exots/context.rb
+- lib/exots/runner.rb
+- lib/exots/version.rb
+homepage: https://github.com/sunteya/exots
+licenses:
+- ISC
+metadata:
+  source_code_uri: https://github.com/sunteya/exots
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A Ruby client for executing JavaScript functions via an IPC bridge.
+test_files: []