rockbox 0.1.0

data/lib/rockbox/events.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Rockbox
+  # Lightweight typed event emitter. The set of valid events is documented
+  # below; emitting an unknown event still works (no enforcement) so plugins
+  # can publish their own.
+  #
+  # Built-in events:
+  #
+  # | Event              | Payload                              |
+  # |--------------------|--------------------------------------|
+  # | :track_changed     | Rockbox::Track                       |
+  # | :status_changed    | Integer (Rockbox::PlaybackStatus)    |
+  # | :playlist_changed  | Rockbox::Playlist                    |
+  # | :ws_open           | nil                                  |
+  # | :ws_close          | nil                                  |
+  # | :ws_error          | Exception/StandardError              |
+  class EventEmitter
+    def initialize
+      @listeners = Hash.new { |h, k| h[k] = [] }
+      @lock = Mutex.new
+    end
+
+    # @example
+    #   client.on(:track_changed) { |track| puts track.title }
+    def on(event, &block)
+      raise ArgumentError, "block required" unless block
+      @lock.synchronize { @listeners[event.to_sym] << block }
+      self
+    end
+
+    # @example
+    #   client.once(:ws_open) { puts "connected!" }
+    def once(event, &block)
+      raise ArgumentError, "block required" unless block
+      wrapper = nil
+      wrapper = lambda do |*args|
+        off(event, wrapper)
+        block.call(*args)
+      end
+      on(event, &wrapper)
+    end
+
+    def off(event, listener = nil, &block)
+      target = block || listener
+      @lock.synchronize do
+        if target.nil?
+          @listeners.delete(event.to_sym)
+        else
+          @listeners[event.to_sym].delete(target)
+        end
+      end
+      self
+    end
+
+    def emit(event, payload = nil)
+      listeners = @lock.synchronize { @listeners[event.to_sym].dup }
+      listeners.each do |listener|
+        if listener.arity.zero? || payload.nil?
+          listener.call
+        else
+          listener.call(payload)
+        end
+      end
+    end
+
+    def remove_all_listeners(event = nil)
+      @lock.synchronize do
+        if event
+          @listeners.delete(event.to_sym)
+        else
+          @listeners.clear
+        end
+      end
+      self
+    end
+  end
+end

data/lib/rockbox/plugin.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rockbox
+  # Context handed to a plugin's #install method. Plugins can issue raw
+  # GraphQL queries and subscribe to the same event stream the SDK uses.
+  PluginContext = Struct.new(:query, :events, keyword_init: true) do
+    def query!(*args, **kwargs)
+      query.call(*args, **kwargs)
+    end
+  end
+
+  # Plugin contract — duck-typed. A plugin must respond to:
+  #   #name        => String  (unique)
+  #   #version     => String
+  #   #install(ctx) => any    (called when registered)
+  #
+  # Optional:
+  #   #description => String
+  #   #uninstall   => any     (called on unregister)
+  #
+  # Inherit from Plugin or just implement the methods directly.
+  class Plugin
+    def name; raise NotImplementedError; end
+    def version; "0.0.0"; end
+    def description; nil; end
+    def install(_context); end
+    def uninstall; end
+  end
+
+  class PluginRegistry
+    def initialize
+      @plugins = {}
+      @lock = Mutex.new
+    end
+
+    def register(plugin, context)
+      name = plugin.name.to_s
+      @lock.synchronize do
+        raise ArgumentError, "Plugin #{name.inspect} is already installed" if @plugins.key?(name)
+      end
+      plugin.install(context)
+      @lock.synchronize { @plugins[name] = plugin }
+      plugin
+    end
+
+    def unregister(name)
+      plugin = @lock.synchronize { @plugins.delete(name.to_s) }
+      plugin&.uninstall if plugin.respond_to?(:uninstall)
+      plugin
+    end
+
+    def installed?(name)
+      @lock.synchronize { @plugins.key?(name.to_s) }
+    end
+
+    def list
+      @lock.synchronize { @plugins.values.dup }
+    end
+  end
+end

data/lib/rockbox/transport.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+
+require_relative "errors"
+require_relative "case_conversion"
+
+module Rockbox
+  # ---------------------------------------------------------------------------
+  # HTTP transport — POSTs GraphQL queries to rockboxd.
+  #
+  # Every outgoing variables hash is camelCased and every incoming `data`
+  # payload is deep-snakeized so callers see idiomatic Ruby keys.
+  # ---------------------------------------------------------------------------
+  class HttpTransport
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 30
+
+    def initialize(url, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      @uri = URI.parse(url)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Execute a GraphQL operation. Returns the snake-cased `data` Hash.
+    def execute(query, variables = nil)
+      body = { query: query }
+      body[:variables] = CaseConversion.deep_camelize(variables) if variables && !variables.empty?
+
+      response = perform_request(body)
+      parse_response(response)
+    end
+
+    private
+
+    def perform_request(body)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = (@uri.scheme == "https")
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      request = Net::HTTP::Post.new(@uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"]       = "application/json"
+      request.body            = JSON.generate(body)
+
+      http.request(request)
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError.new("Failed to reach Rockbox at #{@uri}: #{e.message}", cause: e)
+    end
+
+    def parse_response(response)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise NetworkError, "HTTP #{response.code} #{response.message}"
+      end
+
+      payload = JSON.parse(response.body)
+      if (errors = payload["errors"]) && !errors.empty?
+        raise GraphQLError, errors.map { |e| CaseConversion.deep_snakeize(e) }
+      end
+
+      CaseConversion.deep_snakeize(payload["data"]) || {}
+    rescue JSON::ParserError => e
+      raise NetworkError.new("Invalid JSON response: #{e.message}", cause: e)
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # WebSocket transport — speaks the `graphql-transport-ws` protocol.
+  #
+  # Each call to {#subscribe} returns a "stop" lambda that cancels the
+  # subscription. Reconnection is intentionally simple: the transport is
+  # disposable, so callers should rebuild the client on terminal errors.
+  # ---------------------------------------------------------------------------
+  class WsTransport
+    GRAPHQL_TRANSPORT_WS = "graphql-transport-ws"
+
+    def initialize(url)
+      @url = url
+      @client = nil
+      @lock = Mutex.new
+      @sinks = {}        # subscription id => sink hash
+      @ack = false
+      @ack_signal = ConditionVariable.new
+    end
+
+    # @param query     [String]
+    # @param variables [Hash, nil]
+    # @param sink      [Hash{Symbol => Proc}] keys: :next, :error, :complete
+    # @return          [Proc] call to unsubscribe
+    def subscribe(query, variables, sink)
+      ensure_connected
+
+      sub_id = SecureRandom.uuid
+      @lock.synchronize { @sinks[sub_id] = sink }
+
+      send_message(
+        id: sub_id,
+        type: "subscribe",
+        payload: {
+          query: query,
+          variables: variables ? CaseConversion.deep_camelize(variables) : {}
+        }
+      )
+
+      lambda do
+        send_message(id: sub_id, type: "complete") rescue nil
+        @lock.synchronize { @sinks.delete(sub_id) }
+      end
+    end
+
+    def dispose
+      @lock.synchronize do
+        @sinks.clear
+        if @client
+          begin
+            @client.close
+          rescue StandardError
+            # ignored
+          end
+          @client = nil
+          @ack = false
+        end
+      end
+    end
+
+    private
+
+    def ensure_connected
+      @lock.synchronize do
+        return if @client && @ack
+
+        require "websocket-client-simple" unless defined?(WebSocket::Client::Simple)
+
+        transport = self
+        @ack = false
+
+        @client = WebSocket::Client::Simple.connect(@url, headers: { "Sec-WebSocket-Protocol" => GRAPHQL_TRANSPORT_WS })
+
+        @client.on(:open)    { transport.send(:on_open) }
+        @client.on(:message) { |msg| transport.send(:on_message, msg) }
+        @client.on(:error)   { |err| transport.send(:on_error, err) }
+        @client.on(:close)   { transport.send(:on_close) }
+
+        # Wait for connection_ack before returning.
+        deadline = Time.now + 5.0
+        until @ack
+          remaining = deadline - Time.now
+          raise NetworkError, "Timed out waiting for graphql-transport-ws connection_ack" if remaining <= 0
+          @ack_signal.wait(@lock, remaining)
+        end
+      end
+    end
+
+    def on_open
+      send_message(type: "connection_init", payload: {})
+    end
+
+    def on_message(msg)
+      data = msg.respond_to?(:data) ? msg.data : msg.to_s
+      payload = JSON.parse(data)
+
+      case payload["type"]
+      when "connection_ack"
+        @lock.synchronize do
+          @ack = true
+          @ack_signal.broadcast
+        end
+      when "next"
+        sink = @lock.synchronize { @sinks[payload["id"]] }
+        next_payload = payload["payload"] || {}
+        data_hash = CaseConversion.deep_snakeize(next_payload["data"])
+        sink&.dig(:next)&.call(data: data_hash)
+      when "error"
+        sink = @lock.synchronize { @sinks[payload["id"]] }
+        sink&.dig(:error)&.call(payload["payload"])
+      when "complete"
+        sink = @lock.synchronize { @sinks.delete(payload["id"]) }
+        sink&.dig(:complete)&.call
+      end
+    rescue JSON::ParserError
+      # Drop malformed frames silently; rockboxd never sends them.
+    end
+
+    def on_error(err)
+      sinks = @lock.synchronize { @sinks.values.dup }
+      sinks.each { |s| s[:error]&.call(err) }
+    end
+
+    def on_close
+      @lock.synchronize { @ack = false }
+    end
+
+    def send_message(message)
+      raise NetworkError, "WebSocket is not connected" unless @client
+      @client.send(JSON.generate(message))
+    end
+  end
+end

data/lib/rockbox/types.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Rockbox
+  # Numeric playback states reported by the firmware.
+  module PlaybackStatus
+    STOPPED = 0
+    PLAYING = 1
+    PAUSED  = 3
+
+    def self.name(value)
+      { 0 => :stopped, 1 => :playing, 3 => :paused }[value] || :unknown
+    end
+  end
+
+  module RepeatMode
+    OFF       = 0
+    ALL       = 1
+    ONE       = 2
+    SHUFFLE   = 3
+    AB_REPEAT = 4
+  end
+
+  module ChannelConfig
+    STEREO        = 0
+    STEREO_NARROW = 1
+    MONO          = 2
+    LEFT_MIX      = 3
+    RIGHT_MIX     = 4
+    KARAOKE       = 5
+  end
+
+  module ReplaygainType
+    TRACK   = 0
+    ALBUM   = 1
+    SHUFFLE = 2
+  end
+
+  # Where to insert tracks in the queue (Kodi/Mopidy convention).
+  module InsertPosition
+    NEXT          = 0
+    AFTER_CURRENT = 1
+    LAST          = 2
+    FIRST         = 3
+  end
+
+  # ---------------------------------------------------------------------------
+  # Value objects
+  # ---------------------------------------------------------------------------
+  #
+  # Each type is a Struct that ignores unknown keys at construction so the
+  # firmware can add fields without breaking older SDK builds.
+  # ---------------------------------------------------------------------------
+
+  module Type
+    # Build a Struct that tolerates unknown / missing fields when coming
+    # from a Hash. Struct subclasses raise on unknown keys with `keyword_init`,
+    # so {.from_hash} filters the input.
+    def self.with(*members)
+      klass = Struct.new(*members, keyword_init: true)
+      klass.define_singleton_method(:from_hash) do |hash|
+        return nil if hash.nil?
+        attrs = {}
+        members.each { |m| attrs[m] = hash[m] }
+        new(**attrs)
+      end
+      klass.define_singleton_method(:known_members) { members.dup }
+      klass
+    end
+  end
+
+  Track = Type.with(
+    :id, :title, :artist, :album, :genre, :disc, :track_string, :year_string,
+    :composer, :comment, :album_artist, :grouping,
+    :discnum, :tracknum, :layer, :year, :bitrate, :frequency,
+    :filesize, :length, :elapsed, :path,
+    :album_id, :artist_id, :genre_id, :album_art
+  )
+
+  Album = Type.with(
+    :id, :title, :artist, :year, :year_string, :album_art, :md5,
+    :artist_id, :copyright_message, :tracks
+  )
+
+  Artist = Type.with(
+    :id, :name, :bio, :image, :tracks, :albums
+  )
+
+  SearchResults = Type.with(
+    :artists, :albums, :tracks, :liked_tracks, :liked_albums
+  )
+
+  Playlist = Type.with(
+    :amount, :index, :max_playlist_size, :first_index,
+    :last_insert_pos, :seed, :last_shuffled_start, :tracks
+  )
+
+  SavedPlaylist = Type.with(
+    :id, :name, :description, :image, :folder_id,
+    :track_count, :created_at, :updated_at
+  )
+
+  SavedPlaylistFolder = Type.with(:id, :name, :created_at, :updated_at)
+
+  SmartPlaylist = Type.with(
+    :id, :name, :description, :image, :folder_id, :is_system,
+    :rules, :created_at, :updated_at
+  )
+
+  TrackStats = Type.with(
+    :track_id, :play_count, :skip_count, :last_played, :last_skipped, :updated_at
+  )
+
+  BluetoothDevice = Type.with(
+    :address, :name, :paired, :trusted, :connected, :rssi
+  )
+
+  VolumeInfo = Type.with(:volume, :min, :max)
+
+  Device = Type.with(
+    :id, :name, :host, :ip, :port, :service, :app, :is_connected,
+    :base_url, :is_cast_device, :is_source_device, :is_current_device
+  )
+
+  Entry = Type.with(:name, :attr, :time_write, :customaction, :display_name)
+
+  # File-attribute bit set on directory entries.
+  ENTRY_DIR_BIT = 0x10
+
+  def self.directory?(entry)
+    (entry.attr.to_i & ENTRY_DIR_BIT) != 0
+  end
+
+  SystemStatus = Type.with(
+    :resume_index, :resume_crc32, :resume_elapsed, :resume_offset,
+    :runtime, :topruntime, :dircache_size,
+    :last_screen, :viewer_icon_count, :last_volume_change
+  )
+
+  EqBandSetting       = Type.with(:cutoff, :q, :gain)
+  ReplaygainSettings  = Type.with(:noclip, :type, :preamp)
+  CompressorSettings  = Type.with(:threshold, :makeup_gain, :ratio, :knee, :release_time, :attack_time)
+
+  UserSettings = Type.with(
+    :music_dir, :volume, :balance, :bass, :treble, :channel_config, :stereo_width,
+    :eq_enabled, :eq_precut, :eq_band_settings, :replaygain_settings, :compressor_settings,
+    :crossfade_enabled, :crossfade_fade_in_delay, :crossfade_fade_in_duration,
+    :crossfade_fade_out_delay, :crossfade_fade_out_duration, :crossfade_fade_out_mixmode,
+    :crossfeed_enabled, :crossfeed_direct_gain, :crossfeed_cross_gain,
+    :crossfeed_hf_attenuation, :crossfeed_hf_cutoff,
+    :repeat_mode, :single_mode, :party_mode, :shuffle, :player_name
+  )
+end

data/lib/rockbox/version.rb

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

data/lib/rockbox.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "rockbox/version"
+require_relative "rockbox/errors"
+require_relative "rockbox/types"
+require_relative "rockbox/case_conversion"
+require_relative "rockbox/configuration"
+require_relative "rockbox/transport"
+require_relative "rockbox/events"
+require_relative "rockbox/plugin"
+require_relative "rockbox/client"
+
+# Top-level convenience constructor — `Rockbox.new(host: "...")` is a synonym
+# for `Rockbox::Client.new(host: "...")`.
+module Rockbox
+  def self.new(**kwargs, &block)
+    block ? Client.build(&block) : Client.new(**kwargs)
+  end
+end

data/rockbox.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/rockbox/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "rockbox"
+  spec.version     = Rockbox::VERSION
+  spec.authors     = ["Tsiry Sandratraina"]
+  spec.email       = ["tsiry.sndr@rocksky.app"]
+
+  spec.summary     = "Idiomatic Ruby SDK for Rockbox"
+  spec.description = "Ruby SDK for Rockbox — a builder-friendly, block-friendly GraphQL client " \
+                     "with real-time event subscriptions and a plugin system."
+  spec.homepage    = "https://github.com/tsirysndr/rockbox-zig"
+  spec.license     = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = "#{spec.homepage}/tree/master/sdk/ruby"
+  spec.metadata["bug_tracker_uri"]   = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "https://www.rockbox.org"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "README.md",
+    "rockbox.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "websocket-client-simple", "~> 0.6"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: rockbox
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tsiry Sandratraina
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '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: Ruby SDK for Rockbox — a builder-friendly, block-friendly GraphQL client
+  with real-time event subscriptions and a plugin system.
+email:
+- tsiry.sndr@rocksky.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rockbox.rb
+- lib/rockbox/api/bluetooth.rb
+- lib/rockbox/api/browse.rb
+- lib/rockbox/api/devices.rb
+- lib/rockbox/api/library.rb
+- lib/rockbox/api/playback.rb
+- lib/rockbox/api/playlist.rb
+- lib/rockbox/api/saved_playlists.rb
+- lib/rockbox/api/settings.rb
+- lib/rockbox/api/smart_playlists.rb
+- lib/rockbox/api/sound.rb
+- lib/rockbox/api/system.rb
+- lib/rockbox/case_conversion.rb
+- lib/rockbox/client.rb
+- lib/rockbox/configuration.rb
+- lib/rockbox/errors.rb
+- lib/rockbox/events.rb
+- lib/rockbox/plugin.rb
+- lib/rockbox/transport.rb
+- lib/rockbox/types.rb
+- lib/rockbox/version.rb
+- rockbox.gemspec
+homepage: https://github.com/tsirysndr/rockbox-zig
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tsirysndr/rockbox-zig
+  source_code_uri: https://github.com/tsirysndr/rockbox-zig/tree/master/sdk/ruby
+  bug_tracker_uri: https://github.com/tsirysndr/rockbox-zig/issues
+  documentation_uri: https://www.rockbox.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Idiomatic Ruby SDK for Rockbox
+test_files: []