atradio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2184b3dda3768d90ecd29545dd6caf206ab01350468e1d421df4c9058133f715
+  data.tar.gz: 425ce500b2eaddf704bd4c2c32866370ddf25ff5e49d35fab60e88d86a24dc17
+SHA512:
+  metadata.gz: 103bd19a3eb1d18d944cf28950c01fd20fd43e813ade85dd8c08b9a58331ed0ef06ae626f46d216086ef0818209e7ac709ce1f361067b5382464df9d7cd7d143
+  data.tar.gz: 1cb1687bdfcc56dc20cd12ea31981460abb304fbd9ff8ed64f45e45e10fdb55a5f86c4f6973abd64ecc7c26b8c8e8cab059132529b3c21d0d7e152ab4695ed6b

data/README.md

@@ -0,0 +1,61 @@
+# atradio (Ruby SDK)
+
+The official **Ruby SDK** for [atradio.fm](https://atradio.fm). It binds to the
+shared Rust core (`atradio-sdk`) through the crate's plain **C ABI** using Ruby's
+stdlib [`fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — no `ffi`
+gem, no codegen. The auth / record / reconcile logic is identical to the Rust,
+Go, TypeScript, and Python SDKs.
+
+## Setup
+
+The native library is a build artifact. Build it once, then run:
+
+```bash
+cd sdk/ruby
+./build.sh                 # cargo build + copy the native lib into lib/
+ruby examples/smoke.rb
+```
+
+## Interactive console (IRB)
+
+Play with the SDK in a REPL — the `Atradio` module and `Atradio::Agent` are
+loaded and ready:
+
+```bash
+bin/console                # or: rake console
+```
+
+```ruby
+Atradio.recent_stations(5)
+Atradio.favorite_rkey("rb:...")
+```
+
+## Usage
+
+```ruby
+require "atradio"
+
+# Reads — unauthenticated.
+Atradio.recent_stations(10).each { |s| puts s.dig("station", "name") }
+Atradio.popular_stations(10)
+Atradio.favorites("alice.bsky.social")
+
+# The favorite record key matches every other atradio SDK.
+Atradio.favorite_rkey("rb:...")     # 16-char hex
+
+# Writes — app-password login (persists a session file). Stations are Hashes
+# with camelCase keys (stationId, name, streamUrl, source).
+agent = Atradio::Agent.login("session.json", "alice.bsky.social", "app-password")
+agent.favorite("stationId" => "rb:...", "name" => "KEXP",
+               "streamUrl" => "https://…", "source" => "radio-browser")
+agent.set_play_status(station)
+agent.close
+```
+
+## How it works
+
+- `crates/atradio-uniffi` exposes a plain C ABI (`capi.rs`): opaque agent handle,
+  JSON `{"ok"|"error"}` envelopes, `atradio_string_free`.
+- `lib/atradio.rb` declares those functions with `fiddle` and marshals JSON —
+  the whole binding is one file, no gem dependency beyond stdlib `fiddle`.
+- `build.sh` compiles the crate and drops the native library beside the module.

data/lib/atradio/native.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Resolves the native atradio-uniffi library, downloading a prebuilt from the
+# GitHub release on first use when it isn't already present locally.
+#
+# Order of preference:
+#   1. libatradio_uniffi.<ext> next to this file — a local `./build.sh` dev build.
+#   2. A checksum-verified copy in the user cache, downloaded on first load
+#      (the published-gem path: the ~11 MB lib is not bundled in the gem).
+#
+# The gem ships lib/manifest.json (repo, release tag, one sha256 per target
+# triple) — filled from the release artifacts by sdk/scripts/gen-uniffi-manifest.sh.
+require "json"
+require "rbconfig"
+require "digest"
+require "fileutils"
+require "net/http"
+require "uri"
+
+module Atradio
+  module Native
+    module_function
+
+    def ext
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/ then "dylib"
+      when /mswin|mingw|cygwin/ then "dll"
+      else "so"
+      end
+    end
+
+    def arch
+      a = RbConfig::CONFIG["host_cpu"]
+      case a
+      when /x86_64|amd64/ then "x86_64"
+      when /arm64|aarch64/ then "aarch64"
+      else a
+      end
+    end
+
+    # Canonical target triple matching the release asset names.
+    def triple
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/ then "#{arch}-apple-darwin"
+      when /linux/ then "#{arch}-linux-gnu"
+      when /freebsd/ then "#{arch}-unknown-freebsd"
+      when /netbsd/ then "#{arch}-unknown-netbsd"
+      when /openbsd/ then "#{arch}-unknown-openbsd"
+      else raise Error, "unsupported platform: #{RbConfig::CONFIG["host_os"]}"
+      end
+    end
+
+    def lib_dir
+      File.expand_path("..", __dir__) # sdk/ruby/lib
+    end
+
+    def cache_dir(tag)
+      base = ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache")
+      File.join(base, "atradio", tag)
+    end
+
+    def manifest
+      JSON.parse(File.read(File.join(lib_dir, "manifest.json")))
+    end
+
+    # Absolute path to a loadable native library, fetching it if necessary.
+    def resolve
+      local = File.join(lib_dir, "libatradio_uniffi.#{ext}")
+      return local if File.exist?(local)
+
+      m = manifest
+      t = triple
+      sha = m.dig("checksums", t) or
+        raise Error, "no prebuilt native lib for #{t} (manifest has no checksum)"
+      tag = m["tag"]
+      dest = File.join(cache_dir(tag), "libatradio_uniffi-#{t}.#{ext}")
+      return dest if File.exist?(dest) && Digest::SHA256.file(dest).hexdigest == sha
+
+      download_verify(m["repo"], tag, t, sha, dest)
+      dest
+    end
+
+    def download_verify(repo, tag, triple, sha, dest)
+      url = "https://github.com/#{repo}/releases/download/#{tag}/libatradio_uniffi-#{triple}.#{ext}"
+      body = fetch(url)
+      got = Digest::SHA256.hexdigest(body)
+      raise Error, "checksum mismatch for #{triple}: want #{sha}, got #{got}" unless got == sha
+
+      FileUtils.mkdir_p(File.dirname(dest))
+      tmp = "#{dest}.download"
+      File.binwrite(tmp, body)
+      File.chmod(0o755, tmp)
+      File.rename(tmp, dest)
+    end
+
+    def fetch(url, limit = 5)
+      raise Error, "too many redirects" if limit.zero?
+
+      res = Net::HTTP.get_response(URI(url))
+      case res
+      when Net::HTTPSuccess then res.body
+      when Net::HTTPRedirection then fetch(res["location"], limit - 1)
+      else raise Error, "download failed (#{res.code}) for #{url}"
+      end
+    end
+  end
+end

data/lib/atradio.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Official Ruby SDK for atradio.fm.
+#
+# A thin binding, via Ruby's stdlib `fiddle` (no `ffi` gem), to the plain C ABI
+# of the shared Rust core (`atradio-uniffi` → `atradio-sdk`). The auth / record /
+# reconcile logic is identical to the Rust, Go, TypeScript, and Python SDKs.
+require "fiddle"
+require "fiddle/import"
+require "json"
+
+module Atradio
+  VERSION = "0.1.0"
+
+  # Raised on native-lib resolution failure or an `{"error": …}` envelope.
+  class Error < StandardError; end
+end
+
+require_relative "atradio/native"
+
+module Atradio
+  # Local dev build if present, else a checksum-verified download from the
+  # GitHub release (cached). See Atradio::Native.
+  LIB_PATH = Native.resolve
+
+  module C
+    extend Fiddle::Importer
+    dlload Atradio::LIB_PATH
+    [
+      "char* atradio_recent_stations(const char*, unsigned int)",
+      "char* atradio_popular_stations(const char*, unsigned int)",
+      "char* atradio_global_recently_played(const char*, unsigned int)",
+      "char* atradio_favorites(const char*, const char*, unsigned int)",
+      "char* atradio_favorite_rkey(const char*)",
+      "void atradio_string_free(void*)",
+      "void* atradio_agent_login(const char*, const char*, const char*, const char*)",
+      "char* atradio_last_error()",
+      "void atradio_agent_free(void*)",
+      "char* atradio_agent_favorite(void*, const char*)",
+      "char* atradio_agent_unfavorite(void*, const char*)",
+      "char* atradio_agent_comment(void*, const char*, const char*)",
+      "char* atradio_agent_set_play_status(void*, const char*)",
+      "char* atradio_agent_delete_play_status(void*)",
+      "char* atradio_agent_refresh_session(void*)"
+    ].each { |sig| extern sig }
+  end
+  private_constant :C
+
+  # C strings the core returns aren't length-tagged, so resolve their length
+  # with libc `strlen`.
+  STRLEN = Fiddle::Function.new(
+    Fiddle::Handle::DEFAULT["strlen"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_SIZE_T
+  )
+  private_constant :STRLEN
+
+  # Copy an owned C string into a Ruby string and free the original.
+  def self.take_string(ptr)
+    return nil if ptr.nil? || ptr.null?
+
+    len = STRLEN.call(ptr)
+    str = ptr[0, len].force_encoding("UTF-8")
+    C.atradio_string_free(ptr)
+    str
+  end
+
+  # Parse a `{"ok"|"error"}` envelope, raising Error on failure.
+  def self.unwrap(ptr)
+    parsed = JSON.parse(take_string(ptr))
+    raise Error, parsed["error"] if parsed.key?("error")
+
+    parsed["ok"]
+  end
+
+  # ---- reads (unauthenticated) ----
+
+  def self.recent_stations(limit = 50, base: nil)
+    unwrap(C.atradio_recent_stations(base.to_s, limit))
+  end
+
+  def self.popular_stations(limit = 50, base: nil)
+    unwrap(C.atradio_popular_stations(base.to_s, limit))
+  end
+
+  def self.global_recently_played(limit = 50, base: nil)
+    unwrap(C.atradio_global_recently_played(base.to_s, limit))
+  end
+
+  def self.favorites(actor, limit = 50, base: nil)
+    unwrap(C.atradio_favorites(base.to_s, actor, limit))
+  end
+
+  # The deterministic favorite record key — identical across every atradio SDK.
+  def self.favorite_rkey(station_id)
+    take_string(C.atradio_favorite_rkey(station_id))
+  end
+
+  # ---- authenticated agent ----
+  #
+  # Stations are passed as Hashes with camelCase keys (stationId, name,
+  # streamUrl, source, …), matching the wire record shape.
+  class Agent
+    def self.login(session_path, identifier, password, appview: nil)
+      ptr = C.atradio_agent_login(session_path, identifier, password, appview.to_s)
+      if ptr.null?
+        raise Error, (Atradio.take_string(C.atradio_last_error()) || "login failed")
+      end
+
+      new(ptr)
+    end
+
+    def initialize(ptr)
+      @ptr = ptr
+    end
+
+    def favorite(station)
+      Atradio.unwrap(C.atradio_agent_favorite(@ptr, JSON.generate(station)))
+    end
+
+    def unfavorite(station)
+      Atradio.unwrap(C.atradio_agent_unfavorite(@ptr, JSON.generate(station)))
+    end
+
+    def comment(station, text)
+      Atradio.unwrap(C.atradio_agent_comment(@ptr, JSON.generate(station), text))
+    end
+
+    def set_play_status(station)
+      Atradio.unwrap(C.atradio_agent_set_play_status(@ptr, JSON.generate(station)))
+    end
+
+    def delete_play_status
+      Atradio.unwrap(C.atradio_agent_delete_play_status(@ptr))
+    end
+
+    def refresh_session
+      Atradio.unwrap(C.atradio_agent_refresh_session(@ptr))
+    end
+
+    # Release the native handle. The agent is unusable afterwards.
+    def close
+      return if @ptr.null?
+
+      C.atradio_agent_free(@ptr)
+      @ptr = Fiddle::Pointer.new(0)
+    end
+  end
+end

data/lib/manifest.json

@@ -0,0 +1,12 @@
+{
+  "repo": "tsirysndr/atradio.fm",
+  "tag": "bindings-v0.1.0",
+  "checksums": {
+    "aarch64-apple-darwin": "add588bdc7df1b3d44925df1d30b332921d091cdc2f7a21943c842c7193daca0",
+    "aarch64-linux-gnu": "0eebcd1592907b73caf96250a726591221f61d5669ba57ed87dfd796bf35f2cb",
+    "x86_64-apple-darwin": "bae2f0e29853309b5975c12e227b5cc27766263dac119fa54204d29a1a876ea6",
+    "x86_64-linux-gnu": "2db8025ea5f3dce745ebd6b6ecb64c90cfe8ceaa78d7f0b6afa0bfcc5da239b4",
+    "x86_64-unknown-freebsd": "f7d016cc10f5114404504e27b8286101381d51881bedd5b8457fe686c367bc63",
+    "x86_64-unknown-netbsd": "f22ff3e8972e3914b5a780fbcd8fcdad7a1a14f4ff1336b247882c45c8abe0bf"
+  }
+}

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: atradio
+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: fiddle
+  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'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/atradio.rb
+- lib/atradio/native.rb
+- lib/manifest.json
+homepage: https://github.com/tsirysndr/atradio.fm
+licenses:
+- MIT
+metadata: {}
+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: Official Ruby SDK for atradio.fm (fiddle bindings to the shared Rust core)
+test_files: []