rocksky 0.8.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fa47af05712ec34a47fee263a1483c99053c24a9c391a0598018248ad3f73ed
-  data.tar.gz: a5bd7548931ae1c9abfceacf1ca97c755d1c1e1b6c59be12c52f89f831553d84
+  metadata.gz: 84425f844d397e7187168e44115168f310f5a48269da6b1f3efc424cbf9991aa
+  data.tar.gz: 89e6d0d11fd1f88ec4e80498251f1d1d24cc4e77587860b7c96b0508306a3817
 SHA512:
-  metadata.gz: c0dd411cb63a1e79b51e55ca2eb0376b4bf92903f94ee4459ec764a92071b10900e25f00adafb0ba4d25d35dd3a1ef08c152566d9d10994d074957ddeba4185d
-  data.tar.gz: e896f5451742b2c104aab53dc6cb389cc1f9efa482b37d503a98a70bb2e9cef908cf2a2148a5f484b1aea8609c5314104678f1b9100697fe2f94e4cf5c28a7bf
+  metadata.gz: b48c2675d3ecedc52f6b2c7b70a728d927dd69a2564bfe16bc8b55101dfbf866e44b67957b1ad866c57819b0b66360aa637745a73c87238b0c769aa5b5b5e49a
+  data.tar.gz: bbc58f41ea90eda2c8878cde5e6c182a364a5d8de5f4056ab5e6baad5178c67756cf2f02da5343a2b1a679d83839c02b0c1787de64ec6119a42c979abc9a9e2a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.9.1
+
+- Fix a segfault when tearing down a `RemotePlayer` / `RemoteController`.
+  `#close` freed the native handle while the `#listen` background thread was
+  still blocked inside `#next_command` / `#next_event` (a use-after-free). It now
+  stops the background task and **joins** the listen thread — so the poll has
+  returned — before freeing. `#next_command` / `#next_event` also no-op once the
+  handle is released.
+
 ## 0.3.0
 
 - `feed.get_stories` now accepts optional `feed:` (at-uri) and `following:`

data/lib/rocksky/manifest.json

@@ -1,12 +1,12 @@
 {
   "repo": "tsirysndr/rocksky",
-  "tag": "bindings-v0.5.1",
+  "tag": "bindings-v0.6.0",
   "checksums": {
-    "aarch64-apple-darwin": "2f8ea8e242f2a899b081e44d139d363f79e943427c639e73b92e813a3232752d",
-    "aarch64-linux-gnu": "eba5b2f93e19b77d1f2170baa6161f0bad33663cf5d4bbf8f4977ade3c60d286",
-    "x86_64-apple-darwin": "8e6c25c3cad1e45a241745c503bcd505bb26f6c091243cf90ece0f49a9349126",
-    "x86_64-linux-gnu": "79bbe4cb83535e5ed32b538809ba030bc10214befc9d4fce76540f62568c81c1",
-    "x86_64-unknown-freebsd": "59b4e07b6b12931538a2ae77f6ca2e0b542a3aebd23544f6efcf22c429ba088f",
-    "x86_64-unknown-netbsd": "808ec11ba8cb0e168f399f9f61a8993c8dedfbced51ac57a9922e16e31f1a511"
+    "aarch64-apple-darwin": "e2de89af96e1330427898524254ddb57728453947b607c4dd29fb8ed7c513b27",
+    "aarch64-linux-gnu": "37b8f5ec3812cb15f7eeb75beb44ffe857cca95c11064d1e781eaff6edf7c14d",
+    "x86_64-apple-darwin": "7a550b51fc75e1e4d7c5393423f2920dda980ea8f026c9bde8edd926d18d3795",
+    "x86_64-linux-gnu": "683e9c14579041c77fa69b53f73b43a44432719c608d7af74f950c9263c5c53b",
+    "x86_64-unknown-freebsd": "4ecf5a61000b46111aef2c66e241c97e712c8ef6af386a01afddfe2c05136893",
+    "x86_64-unknown-netbsd": "0c619e60f6cf95c42bbe61adb26be8550024c8cbea08be6de9fb3127db627900"
   }
 }

data/lib/rocksky/remote.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Rocksky
+  # RemotePlayer — build a Rocksky-controllable player in a few lines.
+  #
+  # It speaks the remote-control WebSocket protocol (see remote-ws/PROTOCOL.md)
+  # over the shared Rust core: it registers as a device, advertises what you're
+  # playing (now-playing / status / queue), and invokes your handlers when a
+  # miniplayer sends a command (play/pause/next/previous/seek/enqueue/queue
+  # actions). Heartbeat, reconnect, and the device-id handshake are handled for
+  # you inside the core.
+  #
+  # Commands arrive over a blocking poll (#next_command). Register handlers with
+  # #on and call #listen to spawn a background thread that dispatches them, so you
+  # never write the loop yourself.
+  #
+  #   player = Rocksky::RemotePlayer.connect(token, "My Player")
+  #   player.on(:play)  { engine.play }
+  #   player.on(:pause) { engine.pause }
+  #   player.on(:seek)  { |cmd| engine.seek(cmd[:position]) }
+  #   player.listen
+  #   # …then, as your engine plays:
+  #   player.set_now_playing(title: "Chaser", artist: "Calibro 35",
+  #                          durationMs: 182_320, elapsedMs: 0, isPlaying: true)
+  #   player.set_status("playing")
+  #   player.set_queue(items, 0)
+  #
+  # Records (now-playing / queue items) are passed as Hashes with camelCase keys
+  # (title, artist, album, albumArtist, albumArt, durationMs, elapsedMs,
+  # isPlaying / songUri, albumUri, trackNumber), matching the wire record shape.
+  class RemotePlayer
+    # Connect and register a controllable player in the background. +token+ is a
+    # Rocksky access token (JWT); +name+ is the device-picker label; +url+
+    # defaults to the public endpoint when omitted.
+    def self.connect(token, name, url: nil)
+      ptr = C.rocksky_remote_player_connect(token.to_s, name.to_s, url.to_s)
+      raise Error, (Rocksky.take_string(C.rocksky_last_error()) || "connect failed") if ptr.null?
+
+      new(ptr)
+    end
+
+    def initialize(ptr)
+      @ptr = ptr
+      @handlers = {}
+      @thread = nil
+    end
+
+    # Register a handler for a command action, one of +:play+, +:pause+, +:next+,
+    # +:previous+, +:seek+, +:queue_jump+, +:queue_remove+, +:enqueue+. The block
+    # receives the full symbol-keyed command Hash (e.g. +{ action: "seek",
+    # position: 42000 }+). Returns +self+ for chaining.
+    def on(action, &block)
+      @handlers[action.to_sym] = block
+      self
+    end
+
+    # Block until the next controller command, returned as a symbol-keyed Hash
+    # (e.g. +{ action: "play" }+), or +nil+ once disconnected.
+    def next_command
+      return nil if @ptr.null?
+
+      cmd = Rocksky.unwrap(C.rocksky_remote_player_next_command(@ptr))
+      cmd && Rocksky.symbolize(cmd)
+    end
+
+    # Spawn a background thread that polls #next_command and dispatches each
+    # command to its registered handler until the player disconnects. Returns the
+    # Thread.
+    def listen
+      @thread ||= Thread.new do
+        loop do
+          cmd = next_command
+          break if cmd.nil?
+
+          dispatch(cmd)
+        end
+      end
+    end
+
+    # Advertise the currently-playing track. Call whenever it changes, and
+    # periodically (~every 1–4s) with a fresh +elapsedMs+ so controllers show
+    # smooth progress. +track+ is a camelCase Hash.
+    def set_now_playing(track)
+      Rocksky.unwrap(C.rocksky_remote_player_set_now_playing(@ptr, JSON.generate(track)))
+    end
+
+    # Advertise transport state: "playing", "paused", or "stopped".
+    def set_status(status)
+      Rocksky.unwrap(C.rocksky_remote_player_set_status(@ptr, status.to_s))
+    end
+
+    # Advertise the playback queue (+items+ is an array of camelCase queue-item
+    # Hashes) and the active +index+.
+    def set_queue(items, index)
+      Rocksky.unwrap(C.rocksky_remote_player_set_queue(@ptr, JSON.generate(items), index))
+    end
+
+    # Disconnect and stop the background task. #next_command then returns nil,
+    # which ends the #listen thread. The handle stays valid until #close.
+    def disconnect
+      Rocksky.unwrap(C.rocksky_remote_player_disconnect(@ptr))
+    end
+
+    # Release the native handle. The player is unusable afterwards.
+    def close
+      return if @ptr.null?
+
+      # Stop the background task so a blocked #next_command returns nil and the
+      # #listen loop exits, then WAIT for that thread to leave the native call
+      # before freeing — freeing the handle while a poll is in flight is a
+      # use-after-free (segfault).
+      C.rocksky_remote_player_disconnect(@ptr)
+      @thread&.join unless @thread == Thread.current
+      @thread = nil
+      C.rocksky_remote_player_free(@ptr)
+      @ptr = Fiddle::Pointer.new(0)
+    end
+
+    private
+
+    def dispatch(cmd)
+      handler = @handlers[cmd[:action]&.to_sym]
+      handler&.call(cmd)
+    end
+  end
+
+  # RemoteController — build a Rocksky remote UI in a few lines.
+  #
+  # The other half of the remote-control WebSocket protocol: where
+  # {RemotePlayer} is a controllable player, a controller lists the user's
+  # players, observes what each is playing (now-playing / status / queue), picks
+  # the primary device, and sends commands. Heartbeat, reconnect, and the
+  # register handshake are handled for you inside the core.
+  #
+  # Events arrive over a blocking poll (#next_event). Register handlers with #on
+  # and call #listen to spawn a background dispatch thread.
+  #
+  #   controller = Rocksky::RemoteController.connect(token, "My Controller")
+  #   controller.on(:devices)     { |e| render(e[:devices]) }
+  #   controller.on(:now_playing) { |e| show_track(e[:deviceId], e[:track]) }
+  #   controller.listen
+  #   # …then drive a device:
+  #   controller.set_primary(device_id)
+  #   controller.pause(device_id)
+  #   controller.seek(device_id, 42_000)
+  #
+  # A +nil+ / omitted +target+ broadcasts a command to all of the user's devices.
+  class RemoteController
+    # Connect and register a controller in the background. +url+ defaults to the
+    # public endpoint when omitted.
+    def self.connect(token, name, url: nil)
+      ptr = C.rocksky_remote_controller_connect(token.to_s, name.to_s, url.to_s)
+      raise Error, (Rocksky.take_string(C.rocksky_last_error()) || "connect failed") if ptr.null?
+
+      new(ptr)
+    end
+
+    def initialize(ptr)
+      @ptr = ptr
+      @handlers = {}
+      @thread = nil
+    end
+
+    # Register a handler for a server event type, one of +:devices+,
+    # +:device_registered+, +:device_unregistered+, +:primary_changed+,
+    # +:now_playing+, +:status+, +:queue+. The block receives the full
+    # symbol-keyed event Hash. Returns +self+ for chaining.
+    def on(event_type, &block)
+      @handlers[event_type.to_sym] = block
+      self
+    end
+
+    # Block until the next update, returned as a symbol-keyed Hash (each carries a
+    # +:type+), or +nil+ once disconnected.
+    def next_event
+      return nil if @ptr.null?
+
+      ev = Rocksky.unwrap(C.rocksky_remote_controller_next_event(@ptr))
+      ev && Rocksky.symbolize(ev)
+    end
+
+    # Spawn a background thread that polls #next_event and dispatches each event
+    # to its registered handler until the controller disconnects. Returns the
+    # Thread.
+    def listen
+      @thread ||= Thread.new do
+        loop do
+          ev = next_event
+          break if ev.nil?
+
+          dispatch(ev)
+        end
+      end
+    end
+
+    # Choose the primary (scrobble/profile) device.
+    def set_primary(device_id)
+      Rocksky.unwrap(C.rocksky_remote_controller_set_primary(@ptr, device_id.to_s))
+    end
+
+    # +play+. +target+ is a device id, or omit/nil to broadcast to all devices.
+    def play(target = nil)
+      command("play", target)
+    end
+
+    def pause(target = nil)
+      command("pause", target)
+    end
+
+    def next(target = nil)
+      command("next", target)
+    end
+
+    def previous(target = nil)
+      command("previous", target)
+    end
+
+    # Send a simple command ("play" | "pause" | "next" | "previous").
+    def command(action, target = nil)
+      Rocksky.unwrap(C.rocksky_remote_controller_command(@ptr, action.to_s, target.to_s))
+    end
+
+    # Seek +target+ to +position_ms+ (nil target = broadcast).
+    def seek(target, position_ms)
+      Rocksky.unwrap(C.rocksky_remote_controller_seek(@ptr, target.to_s, position_ms))
+    end
+
+    # Jump to +index+ in +target+'s queue (nil target = broadcast).
+    def queue_jump(target, index)
+      Rocksky.unwrap(C.rocksky_remote_controller_queue_jump(@ptr, target.to_s, index))
+    end
+
+    # Remove queue item +index+ on +target+ (nil target = broadcast).
+    def queue_remove(target, index)
+      Rocksky.unwrap(C.rocksky_remote_controller_queue_remove(@ptr, target.to_s, index))
+    end
+
+    # Enqueue +tracks+ (array of camelCase queue-item Hashes) on +target+. +mode+
+    # is "now" | "next" | "last"; nil target = broadcast.
+    def enqueue(target, tracks, mode: "now", shuffle: false, start_index: 0)
+      Rocksky.unwrap(C.rocksky_remote_controller_enqueue(
+                       @ptr, target.to_s, JSON.generate(tracks), mode.to_s, shuffle ? 1 : 0, start_index
+                     ))
+    end
+
+    # Disconnect and stop the background task. #next_event then returns nil, which
+    # ends the #listen thread. The handle stays valid until #close.
+    def disconnect
+      Rocksky.unwrap(C.rocksky_remote_controller_disconnect(@ptr))
+    end
+
+    # Release the native handle. The controller is unusable afterwards.
+    def close
+      return if @ptr.null?
+
+      # Stop the background task so a blocked #next_event returns nil and the
+      # #listen loop exits, then WAIT for that thread to leave the native call
+      # before freeing — freeing the handle while a poll is in flight is a
+      # use-after-free (segfault).
+      C.rocksky_remote_controller_disconnect(@ptr)
+      @thread&.join unless @thread == Thread.current
+      @thread = nil
+      C.rocksky_remote_controller_free(@ptr)
+      @ptr = Fiddle::Pointer.new(0)
+    end
+
+    private
+
+    def dispatch(event)
+      handler = @handlers[event[:type]&.to_sym]
+      handler&.call(event)
+    end
+  end
+end

data/lib/rocksky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rocksky
-  VERSION = "0.8.1"
+  VERSION = "0.9.1"
 end

data/lib/rocksky.rb

@@ -47,7 +47,26 @@ module Rocksky
       "char* rocksky_agent_shout(void*, const char*, const char*, const char*)",
       "char* rocksky_agent_shout_with_gif(void*, const char*, const char*, const char*, const char*)",
       "char* rocksky_agent_reply_shout_with_gif(void*, const char*, const char*, const char*, const char*, const char*, const char*)",
-      "char* rocksky_agent_refresh_session(void*)"
+      "char* rocksky_agent_refresh_session(void*)",
+      # ---- remote player (a controllable device) ----
+      "void* rocksky_remote_player_connect(const char*, const char*, const char*)",
+      "char* rocksky_remote_player_next_command(void*)",
+      "char* rocksky_remote_player_set_now_playing(void*, const char*)",
+      "char* rocksky_remote_player_set_status(void*, const char*)",
+      "char* rocksky_remote_player_set_queue(void*, const char*, unsigned int)",
+      "char* rocksky_remote_player_disconnect(void*)",
+      "void rocksky_remote_player_free(void*)",
+      # ---- remote controller (a remote UI: drive & observe players) ----
+      "void* rocksky_remote_controller_connect(const char*, const char*, const char*)",
+      "char* rocksky_remote_controller_next_event(void*)",
+      "char* rocksky_remote_controller_set_primary(void*, const char*)",
+      "char* rocksky_remote_controller_command(void*, const char*, const char*)",
+      "char* rocksky_remote_controller_seek(void*, const char*, unsigned long long)",
+      "char* rocksky_remote_controller_queue_jump(void*, const char*, unsigned int)",
+      "char* rocksky_remote_controller_queue_remove(void*, const char*, unsigned int)",
+      "char* rocksky_remote_controller_enqueue(void*, const char*, const char*, const char*, char, unsigned int)",
+      "char* rocksky_remote_controller_disconnect(void*)",
+      "void rocksky_remote_controller_free(void*)"
     ].each { |sig| extern sig }
   end
   private_constant :C
@@ -76,6 +95,20 @@ module Rocksky
     parsed["ok"]
   end
 
+  # Recursively convert Hash string keys to symbols (Arrays walked too). Used by
+  # the remote-control glue so commands/events reach handlers as symbol-keyed
+  # hashes (e.g. cmd[:action], event[:type]).
+  def self.symbolize(obj)
+    case obj
+    when Hash
+      obj.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = symbolize(v) }
+    when Array
+      obj.map { |e| symbolize(e) }
+    else
+      obj
+    end
+  end
+
   # ---- reads (unauthenticated; base: overrides the AppView URL) ----
 
   def self.profile(actor, base: nil)
@@ -269,3 +302,4 @@ module Rocksky
 end
 
 require_relative "rocksky/library"
+require_relative "rocksky/remote"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rocksky
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.1
 platform: ruby
 authors:
 - Rocksky
@@ -83,6 +83,7 @@ files:
 - lib/rocksky/library.rb
 - lib/rocksky/manifest.json
 - lib/rocksky/native.rb
+- lib/rocksky/remote.rb
 - lib/rocksky/version.rb
 - rocksky.gemspec
 homepage: https://github.com/tsirysndr/rocksky