pocketbase 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a51b5e2d68dec39bf14a8b65a1dec80e58ad2f4cd326ce0bcaf1137c9b05ddc5
+  data.tar.gz: 2f9ac3ae8bed190a05489dbe74944ee56b2da2f4f7376783ba8d8b5be57301aa
+SHA512:
+  metadata.gz: dd15eda4c54cc09950085ff926ff8554a3ddef11693c8bcba35188f8291e219ff63273c8c1cf6c6f4949dbfd12e6687ef54f44244feedb8caf731c4ec7216976
+  data.tar.gz: 7502f62ac5d8feb3d7f24a40564d27a7a639d3c6ee72ad52316f283378bce16fedc001ebcd9f92fd028c68f008f96b8be84c4fb1f7e0884ae1bdb2be406860f9

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.1 (2026-10-12)
+
+- Prevent forwarding authorization and cookies across redirect origins; preserve HTTP redirect method/body semantics.
+- Honor string-keyed hook results and preserve request options when `before_send` returns nil.
+- Normalize realtime subscription query options; roll back failed listeners and retry failed subscription updates.
+- Terminate idle SSE readers on disconnect and notify `on_disconnect` on stream interruption before reconnecting.
+- Deliver auth changes reliably when callbacks unsubscribe themselves.
+- Expand home-relative auth file paths and raise persistence errors instead of silently dropping writes.
+- Add offline HTTP/SSE regression checks using local TCP servers.
+
+## 0.1.0 (2026-10-12)
+
+Initial release — full Ruby port of [pocketbase/js-sdk](https://github.com/pocketbase/js-sdk):
+
+- `PocketBase::Client` with `send_request`, `before_send`/`after_send` hooks, `filter` builder, `build_url`
+- `PocketBase::AuthStore` (in-memory) and `PocketBase::FileAuthStore` (persisted), cookie import/export, `valid?`/`superuser?`/`auth_record?`, `on_change`
+- `PocketBase::ClientResponseError` (`status`, `url`, `response`/`data`, `original_error`)
+- Services: records (CRUD + password/OAuth2/OTP auth, password reset, verification, email change, impersonate, superuser auto-refresh), collections, files, logs, settings, backups, health, crons, SQL, batch
+- Realtime SSE subscriptions with background thread + auto-reconnect
+- Zero runtime dependencies (stdlib only)
+- 65 integration tests against a live PocketBase server

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azmi Muwahid
+
+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,275 @@
+# pocketbase (Ruby)
+
+A Ruby port of the official [PocketBase JavaScript SDK](https://github.com/pocketbase/js-sdk) — the full client API for [PocketBase](https://pocketbase.io), written in idiomatic Ruby with **zero runtime dependencies** (stdlib only: `net/http`, `json`, `openssl`…).
+
+> Credit: this gem is a port of [pocketbase/js-sdk](https://github.com/pocketbase/js-sdk), created and maintained by the [PocketBase](https://pocketbase.io) team. All API design credit goes to them; this port just brings it to Ruby.
+
+```ruby
+require "pocketbase"
+
+pb = PocketBase.new("http://127.0.0.1:8090")
+
+# auth
+pb.collection("users").auth_with_password("test@example.com", "1234567890")
+puts pb.auth_store.token
+
+# crud
+post = pb.collection("posts").create("title" => "Hello", "views" => 1)
+list = pb.collection("posts").get_list(1, 30, filter: pb.filter("title ~ {:t}", t: "Hello"), sort: "-created")
+pb.collection("posts").update(post["id"], "views" => 2)
+pb.collection("posts").delete(post["id"])
+
+# realtime
+unsub = pb.collection("posts").subscribe("*") { |e| puts "#{e["action"]}: #{e["record"]["id"]}" }
+sleep 60
+unsub.call
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "pocketbase", "~> 0.1"
+```
+
+Or install directly:
+
+```
+gem install pocketbase
+```
+
+Requires Ruby >= 2.7.
+
+## Client basics
+
+```ruby
+pb = PocketBase.new("http://127.0.0.1:8090")
+# or PocketBase::Client.new(url, auth_store: ..., lang: "en-US")
+
+pb.build_url("/api/health")            # full URL builder
+pb.filter("title ~ {:t} && views > {:v}", t: "hi", v: 5)
+pb.collection("posts")                 # cached RecordService per collection
+pb.create_batch                        # batch request builder
+```
+
+Low-level requests (named `send_request` because `send` is taken by `Object#send`):
+
+```ruby
+pb.send_request("/api/health", method: "GET", timeout: 10)
+```
+
+Options accepted by every service method (all optional):
+
+| Option | Meaning |
+|---|---|
+| `query:` / `params:` | extra query params (merged) |
+| `headers:` | extra headers |
+| `timeout:` | seconds |
+| `filter:`, `sort:`, `expand:`, `fields:` … | any other top-level key becomes a query param (like the js-sdk) |
+
+Hooks:
+
+```ruby
+pb.before_send = ->(url, options) { { url: url, options: options } }
+pb.after_send  = ->(response, data, options) { data } # response.status / .headers / .url
+```
+
+`before_send` accepts symbol- or string-keyed `url`/`options` results. Returning nil keeps current request options.
+Redirects preserve methods and bodies except POST on 301/302 and non-GET/HEAD on 303. Credentials are removed when redirect origin changes.
+
+Errors raise `PocketBase::ClientResponseError` with `#status`, `#url`, `#response` (aliased `#data`), `#original_error`, `#is_abort`.
+
+## Auth store
+
+```ruby
+pb.auth_store.token        # raw JWT
+pb.auth_store.record       # authed record hash
+pb.auth_store.valid?       # token present and unexpired
+pb.auth_store.superuser?   # _superusers collection
+pb.auth_store.auth_record? # regular auth record
+pb.auth_store.save(token, record)
+pb.auth_store.clear
+pb.auth_store.on_change { |token, record| ... } # returns unsubscribe lambda
+
+# cookie helpers (e.g. for Rails controllers)
+cookie = pb.auth_store.export_to_cookie
+pb.auth_store.load_from_cookie(request.headers["Cookie"])
+
+# file-persisted store (like the js-sdk LocalAuthStore)
+pb2 = PocketBase.new(url, auth_store: PocketBase::FileAuthStore.new("~/.pb_auth.json"))
+```
+
+`FileAuthStore` expands `~` in paths. Write failures raise their original filesystem error; do not treat failed saves or clears as persisted.
+
+## Records & auth
+
+```ruby
+posts = pb.collection("posts")
+posts.get_list(1, 30, filter: "...", sort: "-created", expand: "author")
+posts.get_full_list(batch: 200, filter: "...")  # or get_full_list(200, filter: "...")
+posts.get_first_list_item("title = 'Hello'")    # 404 when missing
+posts.get_one("RECORD_ID")
+posts.create("title" => "Hi", "image" => File.open("a.png", "rb")) # file upload -> multipart
+posts.update("RECORD_ID", "title" => "Hi again")
+posts.delete("RECORD_ID")
+
+users = pb.collection("users")
+auth = users.auth_with_password("test@example.com", "secret")
+users.auth_refresh
+users.list_auth_methods
+users.request_password_reset("test@example.com")
+users.confirm_password_reset("TOKEN", "new-pass", "new-pass")
+users.request_verification("test@example.com")
+users.confirm_verification("TOKEN")
+users.request_email_change("new@example.com")
+users.confirm_email_change("TOKEN", "password")
+users.request_otp("test@example.com")           # => { "otpId" => ... }
+users.auth_with_otp("OTP_ID", "password")
+
+# superuser impersonation -> brand new client with the impersonated session
+other = pb.collection("users").impersonate("RECORD_ID")
+
+# superuser token auto-refresh (mirrors js-sdk autoRefreshThreshold, seconds)
+pb.collection("_superusers").auth_with_password("admin@example.com", "secret",
+                                                auto_refresh_threshold: 1800)
+```
+
+### OAuth2
+
+Assisted flow (opens the provider URL via your block, waits on the realtime `@oauth2` channel, exchanges the code):
+
+```ruby
+auth = pb.collection("users").auth_with_oauth2(provider: "google") do |url|
+  puts "Open: #{url}" # or `system("open", url)`
+end
+```
+
+Manual flow:
+
+```ruby
+info = pb.collection("users").oauth2_login_url("google", scopes: ["email"])
+# redirect the user to info["url"], then:
+pb.collection("users").auth_with_oauth2_code("google", code, info["code_verifier"], redirect_url)
+```
+
+## Files
+
+```ruby
+pb.files.get_url(record, "avatar.png")                        # absolute URL
+pb.files.get_url(record, "avatar.png", thumb: "100x100")      # thumbnail
+pb.files.get_url(record, "avatar.png", download: true)        # force download
+pb.files.get_url(record, "avatar.png", token: pb.files.get_token) # protected file
+```
+
+## Realtime
+
+The SSE stream runs in a background thread with automatic reconnect (same backoff as the js-sdk).
+
+```ruby
+unsub = pb.realtime.subscribe("posts/*") { |e| p e["action"] }
+# or via the collection helper:
+unsub = pb.collection("posts").subscribe("*") { |e| p e }
+
+unsub.call                        # remove this listener
+pb.collection("posts").unsubscribe("*")
+pb.realtime.unsubscribe_by_prefix("posts")
+pb.realtime.disconnect             # close the stream (auto-closes when no subs remain)
+pb.realtime.on_disconnect = ->(subs) { puts "disconnected, active: #{subs}" }
+```
+
+## Batch
+
+```ruby
+batch = pb.create_batch
+batch.collection("posts").create("title" => "a")
+batch.collection("posts").update("RECORD_ID", "title" => "b")
+batch.collection("posts").upsert("id" => "MAYBE_ID", "title" => "c")
+batch.collection("posts").delete("OTHER_ID")
+results = batch.send # => [{ "status" => 200, "body" => {...} }, ...]
+```
+
+Note: `/api/batch` is **disabled by default** on the server — enable it in *Settings → Batch* (or via `pb.settings.update`).
+
+## Admin services
+
+```ruby
+pb.settings.get_all
+pb.settings.update(full_settings_hash) # nested structs are replaced wholesale: round-trip get_all
+pb.settings.test_s3("storage")
+pb.settings.test_email("users", "to@example.com", "verification")
+
+pb.backups.get_full_list
+pb.backups.create("backup.zip")   # name must end in .zip
+pb.backups.upload("file" => File.open("backup.zip", "rb"))
+pb.backups.delete("backup.zip")
+pb.backups.restore("backup.zip")
+pb.backups.get_download_url(pb.files.get_token, "backup.zip")
+
+pb.logs.get_list(1, 30, filter: "...")
+pb.logs.get_one("LOG_ID")
+pb.logs.get_stats
+pb.logs.truncate
+
+pb.crons.get_full_list
+pb.crons.run("job-id")
+
+pb.sql.run("SELECT id FROM posts") # superusers only
+
+pb.collections.get_one("COLLECTION_ID")
+pb.collections.create(base_hash)
+pb.collections.update("COLLECTION_ID", "listRule" => "")
+pb.collections.delete("COLLECTION_ID")
+pb.collections.import([col1, col2], delete_missing: false)
+pb.collections.truncate("posts")
+pb.collections.get_scaffolds
+pb.collections.get_all_oauth2_providers
+pb.collections.dry_run_view_query("SELECT id FROM posts")
+
+pb.health.check
+```
+
+## Notes & differences from the js-sdk
+
+- **Synchronous.** No promises; no auto-cancellation of in-flight requests (`auto_cancellation`/`cancel_request` exist as no-ops for API compatibility).
+- **`send_request`** instead of `send` (`Object#send` collision).
+- **Options are plain hashes**, e.g. `get_list(1, 30, filter: "...", timeout: 5)`. Pass request bodies as the first positional hash: `create("title" => "Hi")`.
+- **Responses are hashes** with string keys (parsed JSON), not model classes.
+- **Realtime** uses a background thread + `Queue`-friendly blocks instead of `EventSource`.
+- **OAuth2 popup flow** is replaced by a block-based assisted flow (`auth_with_oauth2 { |url| ... }`) plus a manual `oauth2_login_url` helper.
+- `settings.update` needs the **full settings object** (PocketBase replaces nested structs wholesale — partial nested hashes don't merge).
+- `backups.create` names must end with `.zip`; `/api/batch` must be enabled server-side.
+
+## Development
+
+```bash
+# start a local PocketBase for the test suite
+./pocketbase serve --http 127.0.0.1:8090
+./pocketbase superuser upsert admin@test.com password123
+
+ruby -Ilib -Itest -e 'Dir.glob("test/test_*.rb").each { |f| require_relative f }'
+# or: POCKETBASE_URL=http://127.0.0.1:8090 rake test
+```
+
+Offline checks need no PocketBase process:
+
+```bash
+rake test_offline
+```
+
+### RubyGems release
+
+```bash
+rake build # runs offline checks, then builds pocketbase-0.1.1.gem
+gem push pocketbase-0.1.1.gem --host https://rubygems.org
+```
+
+Publishing requires a RubyGems account with access to the `pocketbase` name and a push-enabled API key (or interactive login). Complete any required MFA challenge. Never commit credentials or API keys. RubyDoc links use the published gem version and its source comments.
+
+## Credits
+
+- [PocketBase](https://pocketbase.io) team — authors of the original [pocketbase/js-sdk](https://github.com/pocketbase/js-sdk) this gem is ported from.
+- [Azmi Muwahid](https://github.com/azmi2409) — Ruby port.
+
+## License
+
+MIT. Port of [pocketbase/js-sdk](https://github.com/pocketbase/js-sdk) (also MIT).

data/lib/pocketbase/auth_store.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PocketBase
+  # In-memory auth store mirroring the js-sdk BaseAuthStore.
+  class AuthStore
+    DEFAULT_COOKIE_KEY = "pb_auth"
+    # crc32 checksum id of the _superusers collection (fallback check, as in js-sdk)
+    SUPERUSERS_COLLECTION_ID = "pbc_3142635823"
+
+    attr_reader :token, :record
+
+    def initialize(token = nil, record = nil)
+      @token = ""
+      @record = nil
+      @on_change_callbacks = []
+      save(token, record) if token || record
+    end
+
+    # Saves the token and record model, triggering on_change callbacks.
+    def save(token, record = nil)
+      @token = token.to_s
+      @record = record
+      trigger_change
+      self
+    end
+
+    # Clears the stored token and record, triggering on_change callbacks.
+    def clear
+      @token = ""
+      @record = nil
+      trigger_change
+      self
+    end
+
+    # Loosely checks whether the store holds a non-expired token.
+    def valid?
+      !Utils.token_expired?(@token)
+    end
+
+    # Loosely checks whether the stored state belongs to a superuser.
+    def superuser?
+      payload = Utils.token_payload(@token)
+      return false unless payload["type"] == "auth"
+
+      collection_name = @record.is_a?(Hash) ? (@record["collectionName"] || @record[:collectionName]) : nil
+      return true if collection_name == "_superusers"
+      return true if collection_name.nil? && payload["collectionId"] == SUPERUSERS_COLLECTION_ID
+
+      false
+    end
+
+    # Loosely checks whether the stored state belongs to a regular auth record.
+    def auth_record?
+      Utils.token_payload(@token)["type"] == "auth" && !superuser?
+    end
+
+    # Registers a callback invoked on every store change with (token, record).
+    # Returns an unsubscribe lambda. Pass fire_immediately: true to invoke
+    # the callback right away with the current state.
+    # Listeners present at dispatch start receive the change even when another
+    # listener unsubscribes itself. New listeners start with the next change.
+    #
+    # @param fire_immediately [Boolean] Deliver current state upon registration
+    # @yield [token, record] Called synchronously when authentication changes
+    # @yieldparam token [String] Current token
+    # @yieldparam record [Hash, nil] Current authenticated record
+    # @return [Proc] Unsubscribe callable
+    # @raise [ArgumentError] If no callback block is given
+    def on_change(fire_immediately: false, &callback)
+      raise ArgumentError, "callback block required" unless callback
+
+      @on_change_callbacks << callback
+      callback.call(@token, @record) if fire_immediately
+      -> { @on_change_callbacks.delete(callback) }
+    end
+
+    # Parses a cookie string and loads the token/record stored under `key`.
+    # (Does not validate the token, same as the js-sdk.)
+    def load_from_cookie(cookie, key = DEFAULT_COOKIE_KEY)
+      raw = parse_cookie(cookie)[key.to_s] || ""
+      data = {}
+      begin
+        parsed = JSON.parse(Utils.decode_uri_component(raw))
+        data = parsed if parsed.is_a?(Hash)
+      rescue StandardError
+        data = {}
+      end
+      save(data["token"] || data[:token] || "", data["record"] || data["model"] || data[:record] || data[:model])
+    end
+
+    # Exports the current store state as a cookie string.
+    # Supported options: :secure, :http_only, :same_site, :path, :domain,
+    # :expires (Time), :max_age (seconds).
+    def export_to_cookie(options = {}, key = DEFAULT_COOKIE_KEY)
+      opts = {
+        secure: true,
+        http_only: true,
+        same_site: "Strict",
+        path: "/",
+      }.merge(options)
+
+      payload = Utils.token_payload(@token)
+      opts[:expires] ||= payload["exp"] ? Time.at(payload["exp"].to_i) : Time.at(0)
+
+      raw_data = {
+        "token" => @token,
+        "record" => @record ? JSON.parse(JSON.generate(@record)) : nil,
+      }
+
+      result = serialize_cookie(key, JSON.generate(raw_data), opts)
+
+      # strip the model down to the bare minimum if the cookie is too large
+      if raw_data["record"] && result.bytesize > 4096
+        rec = raw_data["record"]
+        raw_data["record"] = {
+          "id" => rec["id"],
+          "email" => rec["email"],
+          "collectionId" => rec["collectionId"],
+          "collectionName" => rec["collectionName"],
+          "verified" => rec["verified"],
+        }.compact
+        result = serialize_cookie(key, JSON.generate(raw_data), opts)
+      end
+
+      result
+    end
+
+    private
+
+    def trigger_change
+      @on_change_callbacks.dup.each { |cb| cb&.call(@token, @record) }
+    end
+
+    def parse_cookie(cookie)
+      result = {}
+      cookie.to_s.split(";").each do |pair|
+        k, v = pair.strip.split("=", 2)
+        next if k.nil? || k.empty?
+
+        result[k] = v || ""
+      end
+      result
+    end
+
+    def serialize_cookie(key, value, options)
+      parts = ["#{key}=#{Utils.encode_uri_component(value)}"]
+      parts << "Path=#{options[:path]}" if options[:path]
+      parts << "Domain=#{options[:domain]}" if options[:domain]
+      parts << "Expires=#{options[:expires].utc.strftime("%a, %d %b %Y %H:%M:%S GMT")}" if options[:expires]
+      parts << "Max-Age=#{options[:max_age].to_i}" if options[:max_age]
+      parts << "Secure" if options[:secure]
+      parts << "HttpOnly" if options[:http_only]
+      same_site = options[:same_site]
+      parts << "SameSite=#{same_site == true ? "Strict" : same_site}" if same_site
+      parts.join("; ")
+    end
+  end
+
+  # File-persisted auth store (the Ruby equivalent of js-sdk's LocalAuthStore,
+  # which uses browser localStorage). State is stored as JSON at `path`.
+  class FileAuthStore < AuthStore
+    attr_reader :path
+
+    # Loads existing auth state, or saves supplied initial state.
+    # Parent directory must exist. Missing or unreadable state loads empty.
+    #
+    # @param path [String] File path; relative paths and ~ are expanded
+    # @param token [String, nil] Optional initial token
+    # @param record [Hash, nil] Optional initial authenticated record
+    # @raise [SystemCallError, IOError] If initial state cannot be persisted
+    def initialize(path, token = nil, record = nil)
+      @path = File.expand_path(path.to_s)
+      super()
+      if token || record
+        save(token, record)
+      else
+        load_from_file
+      end
+    end
+
+    # Updates memory, notifies listeners, then writes authentication to disk.
+    # Write failures propagate; memory may already contain the new state.
+    #
+    # @param token [String, nil] Token to save
+    # @param record [Hash, nil] Authenticated record
+    # @return [FileAuthStore] This store
+    # @raise [SystemCallError, IOError] If state cannot be written
+    def save(token, record = nil)
+      super
+      persist_to_file
+      self
+    end
+
+    # Clears authentication in memory and persists the cleared state.
+    # A write failure does not guarantee removal of the previous disk token.
+    #
+    # @return [FileAuthStore] This store
+    # @raise [SystemCallError, IOError] If cleared state cannot be written
+    def clear
+      super
+      persist_to_file
+      self
+    end
+
+    private
+
+    def load_from_file
+      return unless File.exist?(@path)
+
+      data = JSON.parse(File.read(@path))
+      @token = data["token"].to_s
+      @record = data["record"]
+    rescue StandardError
+      @token = ""
+      @record = nil
+    end
+
+    def persist_to_file
+      File.write(@path, JSON.generate({ "token" => @token, "record" => @record }))
+    end
+  end
+end