rocksky 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506387a27a8e92d1310a65f855110efff853b6079d9dbb65d6a3e1e56932cc18
-  data.tar.gz: 9d190b167472ba41881d547b527e501e446a75d844cefd4ff5b3200cd461cc94
+  metadata.gz: 6285f01e3baa73b2791e6b64a2d4d331aa750abe5f50d1e4cafe6263073bf9ad
+  data.tar.gz: 1668269cb59db82bfaf6455e66e493f7dfd9a1c97c5037d9b3eac959a60dd3cf
 SHA512:
-  metadata.gz: 1a82ef8bb90f40689b29067ba2debfe55eb8e099ed0897c3a69b795a3f03e76c49b10ba42d2035377027ea6701b53ac7be2195b2aead08f0a609ebd4e3058e9c
-  data.tar.gz: 78ca04c14127de3ae2b6993a942129ad1d9118679f1c8458807d315744e703932ae3c861fb32349fb615dff4d4086207bc38e19a2361d27a8fa047291576addf
+  metadata.gz: 50c4b9e1f82ce55ea8b9370946461dc8fd9bc6c87ce108ac304cf2835a66b0e6474c7cd07cd1c5a77c6794800cc7082a63abb1e45cc8395dfb8b7a07e82d3aed
+  data.tar.gz: 57b4fd741109bd4cc218d68520b22fef8f5dc5bfa2f1494ac7439722e892d5e60112eb026bb9cc65f8aaa784a537bbacf9078c939b27b859d646b854b85d1993

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.11.0
+
+- Added `Rocksky::Filter`, a fluent RSQL builder (`eq`, `ne`, `gt`, `ge`,
+  `lt`, `le`, `is_in`, `is_out`, `is_null`, `is_not_null`, combined with
+  `#and` / `#or`). Fields are Symbols (`:artist`, `:"track.artist"`); values
+  are quoted/escaped automatically, `*` wildcards stay bare.
+- Added filterable reads: `Rocksky.catalog_songs`, `catalog_artists`,
+  `catalog_albums` (`limit:`, `offset:`, `genre:`, `filter:`) and
+  `Rocksky.scrobble_feed` (`did:`, `following:`, `limit:`, `offset:`,
+  `filter:`). `filter:` takes a `Rocksky::Filter` or a raw RSQL String.
+
 ## 0.10.0
 
 - Remote-player protocol: now-playing records accept optional audio info —

data/README.md

@@ -14,7 +14,7 @@ gem install rocksky
 Or in a Gemfile:
 
 ```ruby
-gem "rocksky", "~> 0.7"
+gem "rocksky", "~> 0.11"
 ```
 
 The gem is pure-Ruby; the native library is fetched from the GitHub release on
@@ -83,6 +83,31 @@ Rocksky.top_artists_interval(limit: 5, interval: :all)
 **Match** — `Rocksky.match_song(title, artist, mb_id: nil, isrc: nil)` resolves a
 bare title + artist into full canonical metadata.
 
+### Filtering
+
+`Rocksky::Filter` builds RSQL expressions for the `filter:` kwarg of
+`catalog_songs`, `catalog_artists`, `catalog_albums` and `scrobble_feed`
+(each also takes `limit:`, `offset:` and — catalogs only — `genre:`). Fields
+are Symbols; dotted selectors on the scrobble feed reach the joined
+track/user/artist (`:"track.artist"`, `:"user.handle"`, …).
+
+```ruby
+filter = Rocksky::Filter.eq(:artist, "Daft Punk")
+                        .and(Rocksky::Filter.gt(:duration, 200_000))
+                        .or(Rocksky::Filter.is_in(:genre, %w[house electro]))
+filter.to_s # => artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+
+Rocksky.catalog_songs(limit: 20, filter: filter)
+Rocksky.scrobble_feed(filter: Rocksky::Filter.eq(:"track.artist", "Daft Punk"))
+```
+
+Constructors: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `is_in`, `is_out` (aliases
+`in`/`out`), `is_null`, `is_not_null`. Combine with `#and` (`;`) and `#or`
+(`,`); an OR operand inside an AND is parenthesized automatically. String
+values are quoted/escaped when they contain reserved characters, and `*`
+wildcards pass through unquoted (`Filter.eq(:artist, "Daft*")`). A raw RSQL
+String is accepted anywhere a `Filter` is.
+
 ### Writes — `Rocksky::Agent`
 
 `Agent.login(session_path, identifier, password, appview:, dedup_path:)` → an

data/lib/rocksky/filter.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Standalone — no native core involved. Loads on its own via
+# `require "rocksky/filter"`.
+module Rocksky
+  # Fluent builder for RSQL filter expressions, accepted by the +filter:+
+  # parameter of the catalog and scrobble-feed queries
+  # (app.rocksky.song.getSongs, app.rocksky.artist.getArtists,
+  # app.rocksky.album.getAlbums, app.rocksky.scrobble.getScrobbles).
+  #
+  #     require "rocksky"
+  #
+  #     filter = Rocksky::Filter.eq(:artist, "Daft Punk")
+  #                             .and(Rocksky::Filter.gt(:duration, 200_000))
+  #                             .or(Rocksky::Filter.is_in(:genre, %w[house electro]))
+  #
+  #     Rocksky.catalog_songs(filter: filter)
+  #     # artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+  #
+  # Fields are Symbols (Strings work too); dotted selectors on the scrobble
+  # feed are written as +:"track.artist"+. String values are quoted and
+  # escaped automatically when they contain characters RSQL reserves; +*+
+  # wildcards pass through unquoted so <tt>Filter.eq(:artist, "Daft*")</tt>
+  # performs a case-insensitive match.
+  class Filter
+    # Characters that never need quoting in an RSQL value (+*+ kept bare so
+    # wildcards work).
+    SAFE_VALUE = /\A[A-Za-z0-9_.:@*+-]+\z/
+    private_constant :SAFE_VALUE
+
+    class << self
+      # +field==value+ — equals; +*+ in string values is a wildcard.
+      def eq(field, value)
+        comparison(field, "==", value)
+      end
+
+      # +field!=value+ — not equals.
+      def ne(field, value)
+        comparison(field, "!=", value)
+      end
+
+      # +field=gt=value+ — greater than.
+      def gt(field, value)
+        comparison(field, "=gt=", value)
+      end
+
+      # +field=ge=value+ — greater than or equal.
+      def ge(field, value)
+        comparison(field, "=ge=", value)
+      end
+
+      # +field=lt=value+ — less than.
+      def lt(field, value)
+        comparison(field, "=lt=", value)
+      end
+
+      # +field=le=value+ — less than or equal.
+      def le(field, value)
+        comparison(field, "=le=", value)
+      end
+
+      # +field=in=(a,b)+ — matches any of the values.
+      def is_in(field, values)
+        list(field, "=in=", values)
+      end
+
+      # +field=out=(a,b)+ — matches none of the values.
+      def is_out(field, values)
+        list(field, "=out=", values)
+      end
+
+      alias in is_in
+      alias out is_out
+
+      # +field==null+ — the field is NULL.
+      def is_null(field)
+        new("#{field}==null", :comparison)
+      end
+
+      # +field!=null+ — the field is not NULL.
+      def is_not_null(field)
+        new("#{field}!=null", :comparison)
+      end
+
+      private
+
+      def comparison(field, op, value)
+        new("#{field}#{op}#{render_value(value)}", :comparison)
+      end
+
+      def list(field, op, values)
+        name = op == "=in=" ? "is_in" : "is_out"
+        raise ArgumentError, "Filter.#{name}(#{field.inspect}, ...) needs at least one value" if values.empty?
+
+        new("#{field}#{op}(#{values.map { |v| render_value(v) }.join(",")})", :comparison)
+      end
+
+      def render_value(value)
+        return value.to_s if value.is_a?(Integer) || value.is_a?(Float) ||
+                             value == true || value == false
+
+        str = value.to_s
+        return str if !str.empty? && SAFE_VALUE.match?(str)
+
+        %("#{str.gsub(/(["\\])/) { "\\#{Regexp.last_match(1)}" }}")
+      end
+    end
+
+    def initialize(expr, kind)
+      @expr = expr
+      @kind = kind
+    end
+
+    # Both sides must match (+;+). An +or+ operand is parenthesized to keep
+    # RSQL precedence.
+    def and(other)
+      Filter.new("#{operand_in_and};#{other.operand_in_and}", :and)
+    end
+
+    # Either side may match (+,+). Never parenthesizes.
+    def or(other)
+      Filter.new("#{@expr},#{other.build}", :or)
+    end
+
+    # The RSQL expression string to send as the +filter+ query param.
+    def build
+      @expr
+    end
+
+    alias to_s build
+
+    protected
+
+    def operand_in_and
+      @kind == :or ? "(#{@expr})" : @expr
+    end
+  end
+end

data/lib/rocksky/manifest.json

@@ -1,12 +1,12 @@
 {
   "repo": "tsirysndr/rocksky",
-  "tag": "bindings-v0.7.0",
+  "tag": "bindings-v0.10.0",
   "checksums": {
-    "aarch64-apple-darwin": "e9a772586564269dccf8448d46162b85fe5290307b818b3a4fc26ff634c2ab57",
-    "aarch64-linux-gnu": "fbfc5d12a8c532f437577f1c2e36c794760e78bb66749af33eef17d14a60cafc",
-    "x86_64-apple-darwin": "81e5628ea2f269ac8efefce85fa5eae093b1d49848aba580da9f267a36f85115",
-    "x86_64-linux-gnu": "3d3de1e3b691416676dd1c09879b14944a5c85d1d8911650113e6ee7783326e2",
-    "x86_64-unknown-freebsd": "b0ad8071e2a6baf1096d4f82221c440e56bf9426e435244ade8687f08edabf69",
-    "x86_64-unknown-netbsd": "08e9ff48d6273e63d6ebdc5eb3882777bc9bd227bc9126478a98c5041e2f1f05"
+    "aarch64-apple-darwin": "36607cf75cc05b79f93570efae0047dfe58f4beff38033f59e9c8c9e03c0e62e",
+    "aarch64-linux-gnu": "d5fcf8a3ca7acba5eaf45db0478360ade6ebfcea7f1dab582ff10696ec77c24e",
+    "x86_64-apple-darwin": "a19daa282e01fa68cb279da28bba52198c928c7771770d4e0a5e10e922a51aa9",
+    "x86_64-linux-gnu": "a6751be73f81d32639b85f3a1f2c6420b7a2346acbc59a5fd534156915d2f918",
+    "x86_64-unknown-freebsd": "e811d322e14ce51498928616c02f0c6228ea765a7f67efef00963a1bbe0c172e",
+    "x86_64-unknown-netbsd": "ce8e555d3ef6caee7dd7c7302feb14b73268ae46dcc9c517d8370c57c93624c6"
   }
 }

data/lib/rocksky/playlist.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rocksky
+  # app.rocksky.playlist.* — the global, AT-Proto-backed playlists.
+  #
+  # Distinct from Rocksky::Library's playlist methods, which drive the
+  # Subsonic/Navidrome library (app.rocksky.library.*).
+  #
+  # Writes publish records to the caller's repo, so they need a +token+ and only
+  # show up in reads once the AppView has ingested the commit.
+  module Playlist
+    module_function
+
+    # The playlist catalog.
+    def list(limit: 50, offset: 0, filter: nil, base: nil)
+      params = { limit: limit, offset: offset }
+      params[:filter] = filter if filter
+      Rocksky.get("app.rocksky.playlist.getPlaylists", params, base: base)
+    end
+
+    # A single playlist with its tracks. +filter+ is an RSQL expression over the
+    # tracks (e.g. 'artist=="Daft Punk"').
+    def get(uri, filter: nil, base: nil)
+      params = { uri: uri }
+      params[:filter] = filter if filter
+      Rocksky.get("app.rocksky.playlist.getPlaylist", params, base: base)
+    end
+
+    # Create a playlist. Returns { "uri" => ..., "cid" => ... }.
+    def create(name, token:, description: nil, picture_url: nil, base: nil)
+      params = { name: name }
+      params[:description] = description if description
+      params[:pictureUrl] = picture_url if picture_url
+      Rocksky.post("app.rocksky.playlist.createPlaylist", params, base: base, token: token)
+    end
+
+    # Rename or re-describe a playlist. Owner only.
+    def update(uri, token:, name: nil, description: nil, picture_url: nil, base: nil)
+      params = { uri: uri }
+      params[:name] = name if name
+      params[:description] = description if description
+      params[:pictureUrl] = picture_url if picture_url
+      Rocksky.post("app.rocksky.playlist.updatePlaylist", params, base: base, token: token)
+    end
+
+    # Add songs by their app.rocksky.song AT-URIs. Owner only. Returns
+    # { "uris" => [...] } — the created entry records.
+    def add_songs(uri, songs, token:, base: nil)
+      Rocksky.post("app.rocksky.playlist.addSongs", { uri: uri, songs: songs },
+                   base: base, token: token)
+    end
+
+    # Remove a song. An entry lives in the repo that added it, so only that repo
+    # can retract it.
+    def remove_track(uri, song_uri, token:, base: nil)
+      Rocksky.post("app.rocksky.playlist.removeTrack", { uri: uri, songUri: song_uri },
+                   base: base, token: token)
+    end
+
+    # Delete a playlist and the caller's own entries. Owner only.
+    def remove(uri, token:, base: nil)
+      Rocksky.post("app.rocksky.playlist.removePlaylist", { uri: uri }, base: base, token: token)
+    end
+  end
+end

data/lib/rocksky/version.rb

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

data/lib/rocksky.rb

@@ -27,10 +27,11 @@ module Rocksky
       "char* rocksky_top_tracks(const char*, unsigned int, unsigned int)",
       "char* rocksky_global_stats(const char*)",
       "char* rocksky_get(const char*, const char*, const char*, const char*)",
+      "char* rocksky_post(const char*, const char*, const char*, const char*)",
       "char* rocksky_update_seen(const char*, const char*, const char*)",
       "char* rocksky_library_get(const char*, const char*, const char*, const char*)",
       "char* rocksky_library_post(const char*, const char*, const char*, const char*)",
-      "char* rocksky_match_song(const char*, const char*, const char*, const char*, const char*)",
+      "char* rocksky_match_song(const char*, const char*, const char*, const char*, const char*, const char*)",
       "char* rocksky_top_tracks_interval(const char*, unsigned int, unsigned int, const char*, unsigned int, const char*, const char*)",
       "char* rocksky_top_artists_interval(const char*, unsigned int, unsigned int, const char*, unsigned int, const char*, const char*)",
       "char* rocksky_song_hash(const char*, const char*, const char*)",
@@ -127,6 +128,51 @@ module Rocksky
     unwrap(C.rocksky_global_stats(base.to_s))
   end
 
+  # ---- catalog + feed reads with RSQL filtering ----
+  #
+  # +filter:+ accepts a Rocksky::Filter (see rocksky/filter.rb) or a raw RSQL
+  # String. Fields are Symbols, e.g. Rocksky::Filter.eq(:artist, "Daft Punk").
+
+  # The song catalog (app.rocksky.song.getSongs), optionally narrowed by
+  # +genre:+ and/or an RSQL +filter:+. Returns { "tracks" => [...] }.
+  def self.catalog_songs(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.song.getSongs", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # The artist catalog (app.rocksky.artist.getArtists). Returns
+  # { "artists" => [...] }.
+  def self.catalog_artists(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.artist.getArtists", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # The album catalog (app.rocksky.album.getAlbums). Returns
+  # { "albums" => [...] }.
+  def self.catalog_albums(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.album.getAlbums", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # A social/global scrobbles feed (app.rocksky.scrobble.getScrobbles). Pass
+  # +did:+ to scope to an actor and +following: true+ for their follow graph.
+  # +filter:+ reaches the joined track/user/artist via dotted fields, e.g.
+  # Rocksky::Filter.eq(:"track.artist", "Daft Punk"). Returns
+  # { "scrobbles" => [...] }.
+  def self.scrobble_feed(did: nil, following: false, limit: 50, offset: 0, filter: nil, base: nil)
+    params = { limit: limit, offset: offset }
+    params[:did] = did unless did.nil?
+    params[:following] = following if following
+    params[:filter] = filter.to_s unless filter.nil?
+    get("app.rocksky.scrobble.getScrobbles", params, base: base)
+  end
+
+  # Shared param assembly for the three catalog reads (omit-nil idiom).
+  def self.catalog_params(limit, offset, genre, filter)
+    params = { limit: limit, offset: offset }
+    params[:genre] = genre unless genre.nil?
+    params[:filter] = filter.to_s unless filter.nil?
+    params
+  end
+  private_class_method :catalog_params
+
   # Universal read escape hatch — call any app.rocksky.* query by nsid. +params+
   # is a hash of string params; the whole read-query catalog is reachable here.
   #
@@ -138,6 +184,14 @@ module Rocksky
     unwrap(C.rocksky_get(base.to_s, nsid, JSON.generate(params), token.to_s))
   end
 
+  # Universal write escape hatch — call any app.rocksky.* procedure whose
+  # arguments ride the query string. Most are auth-gated, so pass +token+.
+  #
+  #   Rocksky.post("app.rocksky.playlist.removePlaylist", { uri: uri }, token: tok)
+  def self.post(nsid, params = {}, base: nil, token: nil)
+    unwrap(C.rocksky_post(base.to_s, nsid, JSON.generate(params), token.to_s))
+  end
+
   # ---- notifications (auth-gated; +token+ required) ----
 
   # The authenticated viewer's unread-notification count. Returns
@@ -163,8 +217,10 @@ module Rocksky
   end
 
   # Resolve full canonical metadata for a bare title + artist (matchSong).
-  def self.match_song(title, artist, mb_id: nil, isrc: nil, base: nil)
-    unwrap(C.rocksky_match_song(base.to_s, title, artist, mb_id.to_s, isrc.to_s))
+  # +album+ steers the match toward that release (case-insensitive) so a
+  # remaster/live/single edition doesn't shadow the intended album.
+  def self.match_song(title, artist, album: nil, mb_id: nil, isrc: nil, base: nil)
+    unwrap(C.rocksky_match_song(base.to_s, title, artist, album.to_s, mb_id.to_s, isrc.to_s))
   end
 
   # Top tracks chart over a typed date window. +interval+ is +:all+, or a pair
@@ -301,5 +357,7 @@ module Rocksky
   end
 end
 
+require_relative "rocksky/filter"
 require_relative "rocksky/library"
+require_relative "rocksky/playlist"
 require_relative "rocksky/remote"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rocksky
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Rocksky
@@ -80,9 +80,11 @@ files:
 - README.md
 - exe/rocksky-console
 - lib/rocksky.rb
+- lib/rocksky/filter.rb
 - lib/rocksky/library.rb
 - lib/rocksky/manifest.json
 - lib/rocksky/native.rb
+- lib/rocksky/playlist.rb
 - lib/rocksky/remote.rb
 - lib/rocksky/version.rb
 - rocksky.gemspec