citrine-remote 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: acc440381ae676270dea4fb9c762015773ad20dc4e62c84b456ca548ebc46edd
+  data.tar.gz: 63c2f4ea3b6eacbb4ca2ec9e02e95d949f20450a01b501e06f581abb19a632e4
+SHA512:
+  metadata.gz: 0ae758da6eac4c119a5e646b17e91c25f50953454ec71db41479be8fe2e0a2c8ff70d59e6637f4c550aa5637a8a5d2f162e8cb456e3662df5be1c7b084f163b4
+  data.tar.gz: ac024f18565080b922c3655f023aa2cc251ec23892b7c7545d1097b1e0e3cf2a18d88529e876b120ea8242d41ebca8cae976ee7d6e9fda5ec64ebbe5cd5ac02b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shiningray
+
+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,104 @@
+# Citrine::Remote — 服务器权威状态的前端镜像原语
+
+从 citrine-remote spike 沉淀的可复用组件。核心主张：**视图只是信号的投影**——
+只要把服务器状态以 Signal 形态镜像到前端，整个 Citrine 视图层（Effect/Component/
+渲染器）零修改获得实时同步。前端状态 = 服务器共享状态的镜像 + 本地瞬时 UI 状态。
+
+## 安装
+
+```bash
+gem install citrine-remote   # 依赖 citrine (>= 0.2.0)，自动带入
+```
+
+或 Gemfile：`gem "citrine-remote"`。仓库内的 examples/ 需克隆本仓库后按下文运行
+（示例用工作区内的 citrine 源码，不消费 rubygems 版本）。
+
+目录布局对齐 gem 惯例，未来可原样迁入 `citrine/lib` 或独立成 gem。
+
+## 架构
+
+```
+权威侧（CRuby 服务器）                镜像侧（CRuby / Opal 浏览器）
+  Citrine::Signal（普通信号）           Citrine::Remote::Session（注册表+分发）
+    ↓ Effect 广播                         ↓ apply_remote（广播但不回传，防回声）
+  Citrine::Remote::Hub                  Citrine::Remote::Signal
+    │ patch 流                              │ set = 乐观生效 + propose
+    └────── Wire（传输适配器，双向） ─────────┘
+```
+
+Wire 契约（回调式鸭子类型，两侧一致）：
+
+| 方法 | 语义 |
+|---|---|
+| `send_msg(hash)` | 发送一条消息 |
+| `on_msg { |hash| }` | 收包回调（字符串键，Session 负责归一化） |
+| `on_close { }` | 断线回调 |
+
+消息协议 v0（SPEC-endpoint-protocol 信封的退化形）：
+`propose`（client→server，写入提案）与 `patch`（server→client，权威广播）。
+
+## API
+
+```ruby
+require "citrine/remote"                      # 平台无关四件（Opal 可编译）
+require "citrine/remote/jsonl_wire"           # CRuby TCP 适配器（按需）
+require "citrine/remote/ws_wire"              # CRuby WS 服务器适配器（按需，spike 级手写）
+require "citrine/remote/browser_ws_wire"      # Opal 浏览器原生 WS 适配器（按需）
+
+# 权威侧：发布信号。Effect 首跑即快照，之后每次 set 自动增量下发。
+hub = Citrine::Remote::Hub.new(wire)
+hub.publish("win:1:geom", geom_signal)
+hub.watch("wm:summary") { list_signal.get.map { ... } }  # 派生值：块内读到的信号即依赖
+hub.unpublish("win:1:geom")
+hub.dispose
+
+# 镜像侧：注册表跨连接存活（WireBox 换线），视图只读信号。
+box = Citrine::Remote::WireBox.new
+session = Citrine::Remote::Session.new(box)
+session.on_patch = ->(key) { ... }            # 可选：来源标注（先于渲染触发）
+box.wire = transport                          # 任一 Wire 契约实现
+geom = session.sig("win:1:geom", 初始值)       # 同一 key 恒为同一实例
+geom.get                                      # 视图订阅，本地命中零延迟
+geom.set(v)                                   # 乐观生效 + 提案（服务器可回滚）
+```
+
+## 运行
+
+```bash
+# 本目录即 .ruby-version（3.3.5）
+rake                              # 16 项测试（纯 CRuby + 内存 wire）
+
+ruby examples/window_server.rb                    # 终端 1：demo1 权威侧
+ruby examples/window_client.rb                    # 终端 2：demo1 镜像侧（单窗口，拖拽提案/回滚）
+
+ruby examples/desktop_server.rb            # 终端 1：demo2 桌面权威侧（多窗口+断线重连）
+ruby examples/desktop_client.rb            # 终端 2：demo2 镜像侧（ASCII 渲染）
+
+ruby examples/browser/ws_server.rb         # 浏览器版服务器（无限循环模式）
+open http://127.0.0.1:4470/       # 真 DOM 桌面投影
+```
+
+浏览器端改动 `examples/browser/app.rb` 后重新编译：
+
+```bash
+cd ../citrine && bundle exec opal -c -Ilib -I../citrine-remote/lib -I../citrine-remote/examples/browser \
+  -o ../citrine-remote/examples/browser/app.js ../citrine-remote/examples/browser/app.rb
+```
+
+## 设计要点（spike 结论）
+
+- **Signal 是远程同步的正确粒度**：视图对远程零感知，ASCII 与 DOM 两个渲染器同验。
+- **防回声在原语内**：`apply_remote`（生效+广播+不回传）一个方法终结回声循环。
+- **幂等收敛白捡**：相等短路使重连快照零冗余渲染；`Effect` 首跑即快照。
+- **权威侧零新原语**：普通 Signal + Effect 即广播器；列表 Effect reconcile 出
+  每窗口的 publish 生命周期（见 `world.rb` 的 `DesktopMirror`）。
+- **平台无关纪律**：`remote.rb` 入口禁止 Thread/Mutex/IO/Native——这是 Opal 编译
+  一次通过的原因。阻塞循环只能待在 CRuby 适配器内部。
+
+## 已知限制与下一步
+
+- [ ] `Citrine::Effect.stack` 跨线程共享——CRuby 多连接服务器需内核线程本地化
+- [ ] Wire 回调槽独占制——正式契约应多监听者或显式独占标注
+- [ ] 断线窗口期提案丢失——正式协议需提案排队 + ack
+- [ ] 部分状态间隙（列表 patch 先于几何 patch）——视图须容忍，或引入复合消息/barrier
+- [ ] 消息信封升格 SPEC-endpoint-protocol（message_id / ask-result / priority）

data/lib/citrine/remote/browser_ws_wire.rb

@@ -0,0 +1,20 @@
+# backtick_javascript: true
+require "native"
+
+module Citrine
+  module Remote
+    # Opal 传输适配器：浏览器原生 WebSocket。仅 Opal 环境加载。
+    # 规则：绝不在 Opal 里手写 WS 协议——浏览器给什么用什么。
+    class BrowserWsWire
+      def initialize(url)
+        @ws = Native(`new WebSocket(#{url})`)
+        @ws.addEventListener("message", ->(ev) { @on_msg&.call(JSON.parse(Native(ev)[:data])) })
+        @ws.addEventListener("close", ->(*) { @on_close&.call })
+      end
+
+      def send_msg(h) = @ws.send(JSON.generate(h))
+      def on_msg(&b) = @on_msg = b
+      def on_close(&b) = @on_close = b
+    end
+  end
+end

data/lib/citrine/remote/hub.rb

@@ -0,0 +1,44 @@
+module Citrine
+  module Remote
+    # 权威侧广播器：把本地信号发布为远程可镜像的 patch 流。
+    # 权威侧不需要新原语——普通 Citrine::Signal + Effect 即广播器：
+    # Effect 创建即首跑，所以连接建立（Hub 创建或 publish 调用）立刻下发快照；
+    # 之后每次 set 自动作为增量 patch 下发；unpublish/dispose 停止。
+    class Hub
+      def initialize(wire)
+        @wire = wire
+        @pubs = {}
+      end
+
+      # 发布一个信号：每次变更广播一条 patch，首跑即发当前值（快照）
+      def publish(key, signal)
+        watch(key) { signal.get }
+      end
+
+      # 发布一个派生值：块内读到的信号即依赖（如列表摘要、计算属性）
+      def watch(key, &block)
+        unpublish(key)
+        @pubs[key] = Citrine::Effect.create { emit_patch(key, block.call) }
+        self
+      end
+
+      def unpublish(key)
+        @pubs.delete(key)&.dispose
+        self
+      end
+
+      def dispose
+        @pubs.keys.each { |k| unpublish(k) }
+        self
+      end
+
+      private
+
+      def emit_patch(key, value)
+        @wire.send_msg("kind" => "patch", "key" => key, "value" => value)
+      rescue StandardError # 写已断开的连接：自愈（Opal 侧 JS 异常同口径）
+        dispose
+      end
+    end
+  end
+end

data/lib/citrine/remote/jsonl_wire.rb

@@ -0,0 +1,33 @@
+module Citrine
+  module Remote
+    # CRuby 传输适配器：JSON Lines over TCPSocket。
+    # 阻塞读循环藏在 #start 的线程里，对外只暴露回调契约。仅 CRuby 加载。
+    class JsonlWire
+      def initialize(io)
+        @io = io
+        @wlock = Mutex.new
+      end
+
+      def on_msg(&b) = @on_msg = b
+      def on_close(&b) = @on_close = b
+
+      def send_msg(h)
+        @wlock.synchronize do
+          @io.write(JSON.generate(h) + "\n")
+          @io.flush
+        end
+      end
+
+      def start
+        Thread.new do
+          begin
+            @io.each_line { |l| @on_msg&.call(JSON.parse(l)) }
+          rescue SystemCallError, IOError, EOFError, JSON::ParserError
+          end
+          @on_close&.call
+        end
+        self
+      end
+    end
+  end
+end

data/lib/citrine/remote/session.rb

@@ -0,0 +1,39 @@
+module Citrine
+  module Remote
+    # 客户端会话：消息分发 + 信号注册表（key → Signal）。
+    # 视图层只读 #sig 拿到的信号，对"远程"零感知。
+    class Session
+      # on_patch：每条 patch 应用**之前**回调（广播是同步渲染，标注来源必须先置位）
+      attr_accessor :on_patch
+
+      def initialize(box)
+        @box = box
+        @registry = {}
+        box.on_msg { |m| dispatch(m) }
+      end
+
+      # 同一 key 始终返回同一个信号实例（注册表即身份映射）
+      def sig(key, init)
+        @registry[key] ||= Signal.new(key, init, wire: @box)
+      end
+
+      def dispatch(msg)
+        return unless msg["kind"] == "patch"
+
+        @on_patch&.call(msg["key"])
+        sig(msg["key"], nil).apply_remote(deep_sym(msg["value"]))
+      end
+
+      private
+
+      # 消息一律字符串键（两侧 JSON 解析口径不同），值统一转符号
+      def deep_sym(v)
+        case v
+        when Hash then v.each_with_object({}) { |(k, val), h| h[k.to_sym] = deep_sym(val) }
+        when Array then v.map { |x| deep_sym(x) }
+        else v
+        end
+      end
+    end
+  end
+end

data/lib/citrine/remote/signal.rb

@@ -0,0 +1,38 @@
+module Citrine
+  module Remote
+    # 远程镜像信号：一个普通的 Citrine::Signal，写入路径分两条腿——
+    #
+    #   #set(v)          本地写入 = 乐观生效 + 向服务器提交提案（propose）。
+    #                    服务器是权威，有权修正：修正经 patch 回滚本地值。
+    #   #apply_remote(v) 服务器下行：生效并广播（视图重渲染），但不回传。
+    #                    防回声的关键操作——回声循环终结在原语里，与应用无关。
+    #
+    # 相等短路继承自 Citrine::Signal：重连快照里值未变的 patch 零渲染，
+    # 幂等收敛是底层语义白捡的，协议层无需设计。
+    class Signal < Citrine::Signal
+      attr_reader :key
+
+      def initialize(key, value, wire:)
+        super(value)
+        @key = key
+        @wire = wire
+      end
+
+      def set(v)
+        return self if v == peek
+
+        super
+        @wire.send_msg("kind" => "propose", "key" => @key, "value" => v)
+        self
+      end
+
+      def apply_remote(v)
+        return self if v == peek
+
+        @value = v
+        broadcast
+        self
+      end
+    end
+  end
+end

data/lib/citrine/remote/version.rb

@@ -0,0 +1,5 @@
+module Citrine
+  module Remote
+    VERSION = "0.1.0"
+  end
+end

data/lib/citrine/remote/wire_box.rb

@@ -0,0 +1,30 @@
+module Citrine
+  module Remote
+    # 可换底层连接的转发器：重连时替换 #wire，信号注册表跨连接存活。
+    # 回调注册在盒子上（盒子稳定、wire 是耗材），换线自动转挂。
+    # 注意：wire 的回调槽归本盒子独占——同一 wire 上不要再注册别的 on_msg/on_close。
+    # 断线期间的本地提案直接丢弃（真实系统应排队或拒绝——v0 从简）。
+    class WireBox
+      def initialize
+        @wire = nil
+        @on_msg = nil
+        @on_close = nil
+      end
+
+      def wire=(w)
+        @wire = w
+        w.on_msg { |m| @on_msg&.call(m) }
+        w.on_close { @on_close&.call }
+      end
+
+      def on_msg(&b) = @on_msg = b
+      def on_close(&b) = @on_close = b
+
+      def send_msg(h)
+        @wire&.send_msg(h)
+      rescue StandardError # 死线写入（IOError/SystemCallError；Opal 侧 JS 异常同口径）：丢弃
+        nil
+      end
+    end
+  end
+end

data/lib/citrine/remote/ws_wire.rb

@@ -0,0 +1,74 @@
+require "digest/sha1"
+require "base64"
+
+module Citrine
+  module Remote
+    # CRuby 传输适配器：零依赖手写 WebSocket 服务器端（RFC6455 文本帧、
+    # 客户端帧带掩码）。spike 级实现——正式部署应换现成 gem 或 AgentOS 传输。
+    # 仅 CRuby 加载。用法：sock = TCPServer.accept 后 WsWire.new(sock) 完成握手。
+    class WsWire
+      GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+      def initialize(sock)
+        @sock = sock
+        @wlock = Mutex.new
+        sock.gets # 请求行
+        headers = {}
+        while (line = sock.gets) && line != "\r\n"
+          k, v = line.split(": ", 2)
+          headers[k.downcase] = v.strip
+        end
+        accept = Base64.strict_encode64(Digest::SHA1.digest(headers["sec-websocket-key"] + GUID))
+        sock.write("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" \
+                   "Connection: Upgrade\r\nSec-WebSocket-Accept: #{accept}\r\n\r\n")
+      end
+
+      def on_msg(&b) = @on_msg = b
+      def on_close(&b) = @on_close = b
+
+      def send_msg(h)
+        payload = JSON.generate(h)
+        head = [0x81].pack("C")
+        len = payload.bytesize
+        head += if len < 126 then [len].pack("C")
+                elsif len < 65_536 then [126, len].pack("Cn")
+                else [127, len].pack("CQ>")
+                end
+        @wlock.synchronize { @sock.write(head + payload) }
+      end
+
+      def start
+        Thread.new do
+          begin
+            loop { read_frame }
+          rescue SystemCallError, IOError, EOFError, JSON::ParserError
+          end
+          @on_close&.call
+        end
+        self
+      end
+
+      private
+
+      def read_frame
+        b1, b2 = read_exact(2).unpack("CC")
+        opcode = b1 & 0x0F
+        len = b2 & 0x7F
+        len = read_exact(2).unpack1("n") if len == 126
+        len = read_exact(8).unpack1("Q>") if len == 127
+        mask = (b2 & 0x80).zero? ? nil : read_exact(4).unpack("C4")
+        payload = read_exact(len)
+        payload = payload.bytes.each_with_index.map { |b, i| b ^ mask[i % 4] }.pack("C*") if mask
+        case opcode
+        when 1 then @on_msg&.call(JSON.parse(payload))
+        when 8 then raise EOFError
+        when 9 then @wlock.synchronize { @sock.write([0x8A, payload.bytesize].pack("CC") + payload) }
+        end
+      end
+
+      def read_exact(n)
+        n.zero? ? "" : (@sock.read(n) or raise EOFError)
+      end
+    end
+  end
+end

data/lib/citrine/remote.rb

@@ -0,0 +1,23 @@
+# Citrine::Remote — 服务器权威状态的前端镜像原语。
+#
+# 平台无关核心纪律：本入口加载的四个文件禁止出现 Thread/Mutex/IO/Native，
+# CRuby 与 Opal 均可加载。传输适配器按需单独 require：
+#   CRuby:  citrine/remote/jsonl_wire（TCP）· citrine/remote/ws_wire（WS 服务器）
+#   Opal:   citrine/remote/browser_ws_wire（浏览器原生 WebSocket）
+#
+# Wire 契约（回调式鸭子类型，两侧一致）：
+#   send_msg(hash)     发送一条消息
+#   on_msg { |hash| }  收包回调（消息一律字符串键，由 Session 归一化）
+#   on_close { }       断线回调
+#
+# 消息协议（v0，SPEC-endpoint-protocol 信封的退化形）：
+#   client→server  {"kind":"propose","key":...,"value":...}   写入提案
+#   server→client  {"kind":"patch",  "key":...,"value":...}   权威广播
+require "json"
+require "citrine/signal"
+
+require "citrine/remote/version"
+require "citrine/remote/signal"
+require "citrine/remote/wire_box"
+require "citrine/remote/session"
+require "citrine/remote/hub"

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: citrine-remote
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ShiningRay
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: citrine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Citrine::Remote：把服务器权威状态以 Signal 形态镜像到前端。视图层零修改获得实时同步——前端状态 = 服务器共享状态的镜像
+  + 本地瞬时 UI 状态。提供 Remote::Signal（乐观提案/权威回滚）、Hub（权威侧广播器）、Session（镜像侧分发）与可替换的传输适配器（CRuby
+  TCP/WebSocket、Opal 浏览器原生 WebSocket）。
+email:
+- shiningray@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/citrine/remote.rb
+- lib/citrine/remote/browser_ws_wire.rb
+- lib/citrine/remote/hub.rb
+- lib/citrine/remote/jsonl_wire.rb
+- lib/citrine/remote/session.rb
+- lib/citrine/remote/signal.rb
+- lib/citrine/remote/version.rb
+- lib/citrine/remote/wire_box.rb
+- lib/citrine/remote/ws_wire.rb
+homepage: https://github.com/ShiningRay/citrine-remote
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ShiningRay/citrine-remote
+  changelog_uri: https://github.com/ShiningRay/citrine-remote/blob/main/README.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Server-authoritative state mirroring for Citrine: views stay plain Signal
+  projections'
+test_files: []