pocketbase 0.1.1

data/lib/pocketbase/client.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module PocketBase
+  # PocketBase API client (port of the js-sdk Client).
+  #
+  #   pb = PocketBase::Client.new("http://127.0.0.1:8090")
+  #   pb.collection("users").auth_with_password("test@example.com", "1234567890")
+  class Client
+    # Options that are treated as send options; anything else passed at the
+    # top level of an options hash is moved into the query string
+    # (mirrors js-sdk normalizeUnknownQueryParams).
+    KNOWN_SEND_OPTIONS = %i[
+      method headers body query params request_key timeout
+      fetch signal
+    ].freeze
+
+    attr_accessor :base_url, :lang, :auth_store, :before_send, :after_send
+    attr_reader :settings, :collections, :files, :logs, :realtime,
+                :health, :backups, :crons, :sql
+
+    def initialize(base_url = "/", auth_store: nil, lang: "en-US")
+      @base_url = base_url.to_s
+      @lang = lang
+      @auth_store = auth_store || AuthStore.new
+      @before_send = nil
+      @after_send = nil
+      @record_services = {}
+      @enable_auto_cancellation = true
+
+      @settings = Services::SettingsService.new(self)
+      @collections = Services::CollectionService.new(self)
+      @files = Services::FileService.new(self)
+      @logs = Services::LogService.new(self)
+      @realtime = Services::RealtimeService.new(self)
+      @health = Services::HealthService.new(self)
+      @backups = Services::BackupService.new(self)
+      @crons = Services::CronService.new(self)
+      @sql = Services::SQLService.new(self)
+    end
+
+    # Returns the RecordService for a collection (cached per idOrName).
+    def collection(id_or_name)
+      key = id_or_name.to_s
+      @record_services[key] ||= Services::RecordService.new(self, key)
+    end
+
+    # Creates a new batch handler for transactional multi-requests.
+    #
+    #   batch = pb.create_batch
+    #   batch.collection("posts").create(title: "hello")
+    #   batch.collection("posts").update("RECORD_ID", title: "hi")
+    #   batch.send
+    def create_batch
+      Services::BatchService.new(self)
+    end
+
+    # Globally enables/disables auto cancellation of duplicated requests.
+    # Note: requests are synchronous in the Ruby client, so there is nothing
+    # to cancel; the flag is accepted for API compatibility.
+    def auto_cancellation(enable)
+      @enable_auto_cancellation = !!enable
+      self
+    end
+
+    # No-op in the synchronous Ruby client (kept for API compatibility).
+    def cancel_request(_request_key)
+      self
+    end
+
+    # No-op in the synchronous Ruby client (kept for API compatibility).
+    def cancel_all_requests
+      self
+    end
+
+    # Builds a filter expression with `{:param}` placeholders populated
+    # from params (see Utils.build_filter).
+    def filter(raw, params = nil)
+      Utils.build_filter(raw, params)
+    end
+
+    # Builds a full client URL by safely concatenating the given path.
+    def build_url(path = nil)
+      url = @base_url.dup
+      if path && !path.to_s.empty?
+        url += "/" unless url.end_with?("/")
+        p = path.to_s
+        p = p[1..] if p.start_with?("/")
+        url += p
+      end
+      url
+    end
+
+    # Sends an API HTTP request.
+    #
+    # Options:
+    #   method:  "GET" (default), "POST", "PATCH", "PUT", "DELETE", ...
+    #   headers: Hash of request headers
+    #   body:    Hash (sent as JSON, or as multipart when it has file values),
+    #            a PocketBase::MultipartBody, or a raw String
+    #   query:   Hash of query params (merged with legacy :params)
+    #   timeout: request timeout in seconds
+    #   Any other top-level option is moved into the query string.
+    #
+    # The before_send hook receives (url, options) and may return a Hash with
+    # symbol or string keys for url/options; nil preserves current options.
+    # The after_send hook receives (ResponseInfo, parsed_data, options), and
+    # its return value becomes the result, including the API error payload.
+    # Redirects drop credentials across origins. POST becomes GET on 301/302;
+    # non-GET/HEAD becomes GET on 303. Other redirects retain method and body.
+    #
+    # @param path [String] API path relative to base_url
+    # @param options [Hash] Request options and extra query parameters
+    # @return [Hash, Array, nil] Parsed JSON, nil for an empty body, or hook result
+    # @raise [ClientResponseError] On transport errors or HTTP status >= 400
+    # @example Request health with a timeout
+    #   client.send_request("/api/health", timeout: 10)
+    #
+    # Raises PocketBase::ClientResponseError on transport or API errors.
+    def send_request(path, options = {})
+      options = init_send_options(options)
+      url = build_url(path)
+
+      if @before_send
+        result = @before_send.call(url, options)
+        result = normalize_hook_result(result)
+        url = result[:url] if result[:url]
+        options = result[:options] if result[:options]
+      end
+
+      query = options.delete(:query)
+      if query && !query.empty?
+        serialized = Utils.serialize_query_params(query)
+        url += (url.include?("?") ? "&" : "?") + serialized unless serialized.empty?
+      end
+
+      method = (options[:method] || "GET").to_s.upcase
+      headers = options[:headers] || {}
+      body, content_type = prepare_body(options[:body], headers)
+      headers = headers.dup
+      headers["Content-Type"] = content_type if content_type && !header_present?(headers, "Content-Type")
+      timeout = options[:timeout]
+
+      final_url = url
+      response = perform_request(url, method, headers, body, timeout) do |u|
+        final_url = u
+      end
+
+      data = parse_response_body(response)
+
+      if @after_send
+        data = @after_send.call(ResponseInfo.new(response, final_url), data, options)
+      end
+
+      if response.code.to_i >= 400
+        raise ClientResponseError.new(
+          url: final_url,
+          status: response.code.to_i,
+          response: data.is_a?(Hash) ? data : {},
+          original_error: nil
+        )
+      end
+
+      data
+    rescue ClientResponseError
+      raise
+    rescue StandardError => e
+      raise ClientResponseError.wrap(e, url: url.to_s)
+    end
+
+    # Registers token auto-refresh for superuser sessions, mirroring the
+    # js-sdk autoRefreshThreshold behavior: before each request the token is
+    # refreshed when it expires within `threshold` seconds, falling back to
+    # re-authentication when refresh fails.
+    def register_auto_refresh(threshold, refresh_func, reauthenticate_func)
+      reset_auto_refresh
+
+      old_before_send = @before_send
+      old_record = @auth_store.record
+
+      unsub = @auth_store.on_change do |new_token, model|
+        if new_token.to_s.empty? || model_id(model) != model_id(old_record) ||
+           (collection_id_of(model) || collection_id_of(old_record)) &&
+             collection_id_of(model) != collection_id_of(old_record)
+          reset_auto_refresh
+        end
+      end
+
+      reset_fn = lambda do
+        unsub.call
+        @before_send = old_before_send
+        remove_instance_variable(:@_reset_auto_refresh) if defined?(@_reset_auto_refresh)
+      end
+      @_reset_auto_refresh = reset_fn
+
+      @before_send = lambda do |url, send_options|
+        old_token = @auth_store.token
+        query = send_options[:query] || {}
+
+        unless query[:autoRefresh] || query["autoRefresh"]
+          is_valid = @auth_store.valid?
+          if is_valid && Utils.token_expired?(@auth_store.token, threshold)
+            begin
+              refresh_func.call
+            rescue StandardError
+              is_valid = false
+            end
+          end
+          reauthenticate_func.call unless is_valid
+
+          headers = (send_options[:headers] || {}).dup
+          headers.each do |k, v|
+            if k.to_s.downcase == "authorization" && v == old_token && !@auth_store.token.empty?
+              headers[k] = @auth_store.token
+              break
+            end
+          end
+          send_options = send_options.merge(headers: headers)
+        end
+
+        if old_before_send
+          old_before_send.call(url, send_options)
+        else
+          { url: url, options: send_options }
+        end
+      end
+      self
+    end
+
+    def reset_auto_refresh
+      @_reset_auto_refresh&.call
+      self
+    end
+
+    private
+
+    def model_id(model)
+      model.is_a?(Hash) ? (model["id"] || model[:id]) : nil
+    end
+
+    def collection_id_of(model)
+      model.is_a?(Hash) ? (model["collectionId"] || model[:collectionId]) : nil
+    end
+
+    def normalize_hook_result(result)
+      return {} if result.nil?
+      if result.is_a?(Hash) && (result.key?(:url) || result.key?("url") ||
+                               result.key?(:options) || result.key?("options"))
+        return { url: result[:url] || result["url"], options: result[:options] || result["options"] }
+      end
+
+      # legacy behavior: the whole result replaces the options
+      { options: result }
+    end
+
+    def init_send_options(options)
+      normalized = {}
+      (options || {}).each { |k, v| normalized[k.to_sym] = v }
+      options = { method: "GET" }.merge(normalized)
+
+      # merge legacy :params into :query
+      query = {}
+      query.merge!(options.delete(:params)) if options[:params]
+      query.merge!(options.delete(:query)) if options[:query]
+
+      # move unknown send options into the query (js-sdk compatibility)
+      options.keys.each do |key|
+        next if KNOWN_SEND_OPTIONS.include?(key.to_sym)
+
+        query[key] = options.delete(key)
+      end
+      options[:query] = query
+
+      headers = {}
+      (options[:headers] || {}).each { |k, v| headers[k.to_s] = v }
+
+      # default json content type unless the body needs multipart
+      body = options[:body]
+      unless header_present?(headers, "Content-Type") || body.is_a?(MultipartBody) ||
+             (body.is_a?(Hash) && Multipart.has_file_field?(body))
+        headers["Content-Type"] = "application/json"
+      end
+
+      headers["Accept-Language"] = @lang unless header_present?(headers, "Accept-Language")
+
+      if @auth_store.token && !@auth_store.token.empty? && !header_present?(headers, "Authorization")
+        headers["Authorization"] = @auth_store.token
+      end
+
+      options[:headers] = headers
+      options
+    end
+
+    def header_present?(headers, name)
+      headers.keys.any? { |k| k.to_s.downcase == name.downcase }
+    end
+
+    def prepare_body(body, headers)
+      return [nil, nil] if body.nil?
+
+      if body.is_a?(MultipartBody)
+        return [body.to_s, body.content_type]
+      end
+
+      if body.is_a?(Hash) && Multipart.has_file_field?(body)
+        form = Multipart.build(body)
+        return [form.to_s, form.content_type]
+      end
+
+      ct = nil
+      headers.each { |k, v| ct = v if k.to_s.downcase == "content-type" }
+      if (ct.nil? || ct.include?("application/json")) && !body.is_a?(String)
+        return [JSON.generate(body), "application/json"]
+      end
+
+      [body.to_s, nil]
+    end
+
+    def parse_response_body(response)
+      raw = response.body
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue StandardError
+      {}
+    end
+
+    def perform_request(url, method, headers, body, timeout, redirects = 5, &url_tracker)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      if timeout
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+      end
+
+      request_class = {
+        "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post,
+        "PUT" => Net::HTTP::Put, "PATCH" => Net::HTTP::Patch,
+        "DELETE" => Net::HTTP::Delete, "HEAD" => Net::HTTP::Head,
+        "OPTIONS" => Net::HTTP::Options,
+      }[method] || Net::HTTP::Get
+
+      req = request_class.new(uri.request_uri)
+      headers.each { |k, v| req[k.to_s] = v.to_s }
+      req.body = body if body
+
+      response = http.request(req)
+
+      case response
+      when Net::HTTPRedirection
+        raise ClientResponseError.new(url: url, status: response.code.to_i, response: {}) if redirects <= 0
+
+        location = response["location"]
+        target = URI.join(url, location)
+        new_url = target.to_s
+        if [uri.scheme, uri.host, uri.port] != [target.scheme, target.host, target.port]
+          headers = headers.reject { |key, _| %w[authorization cookie proxy-authorization].include?(key.to_s.downcase) }
+        end
+        url_tracker&.call(new_url)
+        switch_to_get = (%w[301 302].include?(response.code) && method == "POST") ||
+                        (response.code == "303" && !%w[GET HEAD].include?(method))
+        new_method = switch_to_get ? "GET" : method
+        if switch_to_get
+          body = nil
+          headers = headers.reject { |key, _| %w[content-type content-length transfer-encoding].include?(key.to_s.downcase) }
+        end
+        perform_request(new_url, new_method, headers, body,
+                        timeout, redirects - 1, &url_tracker)
+      else
+        response
+      end
+    end
+  end
+
+  # Lightweight response view passed to the after_send hook.
+  class ResponseInfo
+    attr_reader :status, :headers, :url
+
+    def initialize(net_response, url)
+      @status = net_response.code.to_i
+      @headers = {}
+      net_response.each_header { |k, v| @headers[k] = v }
+      @url = url
+    end
+  end
+end

data/lib/pocketbase/client_response_error.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module PocketBase
+  # Wraps and normalizes any error raised by Client#send_request,
+  # mirroring the js-sdk ClientResponseError.
+  class ClientResponseError < StandardError
+    attr_reader :url, :status, :response, :original_error
+    attr_accessor :is_abort
+
+    def initialize(err_data = nil)
+      @url = ""
+      @status = 0
+      @response = {}
+      @is_abort = false
+      @original_error = nil
+
+      if err_data.is_a?(Hash)
+        @original_error = err_data[:original_error] || err_data["originalError"] || err_data["original_error"]
+        @url = err_data[:url] || err_data["url"] || ""
+        @status = err_data[:status] || err_data["status"] || 0
+        @is_abort = !!(err_data[:is_abort] || err_data["isAbort"] || err_data["is_abort"])
+        resp = err_data[:response] || err_data["response"] ||
+               err_data[:data] || err_data["data"]
+        @response = resp.is_a?(Hash) ? resp : {}
+      elsif err_data.is_a?(ClientResponseError)
+        @original_error = err_data.original_error
+        @url = err_data.url
+        @status = err_data.status
+        @response = err_data.response
+        @is_abort = err_data.is_abort
+      elsif !err_data.nil?
+        @original_error = err_data
+      end
+
+      @original_error ||= err_data unless err_data.is_a?(ClientResponseError) || err_data.is_a?(Hash)
+
+      msg = @response["message"] || @response[:message]
+      if msg.nil? && err_data.is_a?(Hash)
+        msg = err_data[:message] || err_data["message"]
+      end
+      msg ||= if @is_abort
+                "The request was aborted."
+              elsif @original_error.is_a?(SystemCallError) || connection_refused?(@original_error)
+                "Failed to connect to the PocketBase server."
+              else
+                "Something went wrong."
+              end
+
+      super(msg.to_s)
+    end
+
+    # Alias for #response (backward compatibility with the js-sdk `.data`).
+    def data
+      @response
+    end
+
+    def to_h
+      {
+        "url" => @url,
+        "status" => @status,
+        "response" => @response,
+        "isAbort" => @is_abort,
+        "message" => message,
+      }
+    end
+
+    # Wraps any raised error into a ClientResponseError (no-op if already one).
+    def self.wrap(err, url: "", status: 0)
+      return err if err.is_a?(ClientResponseError)
+
+      data = {}
+      unless connection_error?(err)
+        data = { "message" => err.message } if err.respond_to?(:message) && err.message && !err.message.empty?
+      end
+      new({ url: url, status: status, response: data, original_error: err })
+    end
+
+    # Loose check for transport-level connection failures.
+    def self.connection_error?(err)
+      return true if err.is_a?(SystemCallError)
+      return true if err.is_a?(Net::OpenTimeout) || err.is_a?(Net::ReadTimeout)
+
+      msg = err.respond_to?(:message) ? err.message.to_s : ""
+      msg.include?("ECONNREFUSED") || msg.include?("connection refused") ||
+        msg.include?("Failed to open TCP connection")
+    end
+
+    private
+
+    def connection_refused?(err)
+      self.class.connection_error?(err)
+    end
+  end
+end

data/lib/pocketbase/multipart.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module PocketBase
+  # Minimal multipart/form-data builder (stdlib only).
+  class MultipartBody
+    attr_reader :boundary
+
+    def initialize(boundary = nil)
+      @boundary = boundary || "----PocketBaseRuby#{SecureRandom.hex(16)}"
+      @parts = [] # each entry: [headers_array, body_string]
+    end
+
+    def add_field(name, value)
+      @parts << [
+        [["Content-Disposition", %(form-data; name="#{name}")]],
+        value.to_s,
+      ]
+      self
+    end
+
+    def add_json_payload(hash)
+      add_field("@jsonPayload", JSON.generate(hash))
+    end
+
+    def add_file(name, filename, content_type, data)
+      @parts << [
+        [
+          ["Content-Disposition", %(form-data; name="#{name}"; filename="#{filename}")],
+          ["Content-Type", content_type || "application/octet-stream"],
+        ],
+        data.to_s.b,
+      ]
+      self
+    end
+
+    def content_type
+      "multipart/form-data; boundary=#{@boundary}"
+    end
+
+    def to_s
+      # binary accumulator so arbitrary file bytes never raise
+      # Encoding::CompatibilityError when appended
+      out = "".b
+      @parts.each do |headers, body|
+        out << "--#{@boundary}\r\n".b
+        headers.each { |k, v| out << "#{k}: #{v}\r\n".b }
+        out << "\r\n".b
+        out << body.to_s.b
+        out << "\r\n".b
+      end
+      out << "--#{@boundary}--\r\n".b
+      out
+    end
+  end
+
+  module Multipart
+    module_function
+
+    # A value counts as a file when it is a File/IO object or a
+    # { filename:, data: } / { "filename" =>, "data" => } style hash.
+    def file_value?(value)
+      return true if value.is_a?(File)
+      return true if value.is_a?(Hash) && (value.key?(:filename) || value.key?("filename") ||
+                                          value.key?(:data) || value.key?("data"))
+      return true if value.respond_to?(:read) && !value.is_a?(String)
+
+      false
+    end
+
+    def has_file_field?(body)
+      return false unless body.is_a?(Hash)
+
+      body.each_value do |val|
+        values = val.is_a?(Array) ? val : [val]
+        return true if values.any? { |v| file_value?(v) }
+      end
+      false
+    end
+
+    # Mirrors js-sdk convertToFormDataIfNeeded: plain Hash/Array values are
+    # sent via @jsonPayload parts to avoid implicit string normalization,
+    # files become regular multipart file parts.
+    def build(body)
+      form = MultipartBody.new
+      (body || {}).each do |key, val|
+        next if val.nil?
+
+        key = key.to_s
+        if val.is_a?(Hash) && !file_value?(val)
+          form.add_json_payload({ key => val })
+        elsif val.is_a?(Array) && !val.any? { |v| file_value?(v) } && val.any? { |v| v.is_a?(Hash) || v.is_a?(Array) }
+          form.add_json_payload({ key => val })
+        elsif val.is_a?(Array)
+          val.each { |v| append_value(form, key, v) }
+        else
+          append_value(form, key, val)
+        end
+      end
+      form
+    end
+
+    def append_value(form, key, val)
+      if file_value?(val)
+        info = file_info(val, key)
+        form.add_file(key, info[:filename], info[:content_type], info[:data])
+      elsif val.is_a?(Hash) || val.is_a?(Array)
+        form.add_json_payload({ key => val })
+      else
+        form.add_field(key, val)
+      end
+    end
+
+    def file_info(value, default_name = "file")
+      case value
+      when File
+        value.binmode
+        {
+          filename: File.basename(value.path),
+          content_type: nil,
+          data: value.read,
+        }
+      when Hash
+        {
+          filename: value[:filename] || value["filename"] || default_name,
+          content_type: value[:content_type] || value["content_type"],
+          data: value[:data] || value["data"],
+        }
+      else # IO-like (StringIO, Tempfile, ...)
+        {
+          filename: (value.respond_to?(:path) && value.path ? File.basename(value.path.to_s) : default_name),
+          content_type: nil,
+          data: value.read,
+        }
+      end
+    end
+  end
+end

data/lib/pocketbase/services/backup_service.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PocketBase
+  module Services
+    # Backup service (port of js-sdk BackupService).
+    class BackupService < BaseService
+      # Returns the list of all available backup files.
+      def get_full_list(options = {})
+        opts = send_options({ method: "GET" }, options)
+        @client.send_request("/api/backups", opts)
+      end
+
+      # Initializes a new backup. Returns true.
+      def create(basename, options = {})
+        opts = send_options({ method: "POST", body: { "name" => basename } }, options)
+        @client.send_request("/api/backups", opts)
+        true
+      end
+
+      # Uploads an existing backup file.
+      #
+      #   pb.backups.upload(file: File.open("backup.zip"))
+      #   pb.backups.upload("file" => { filename: "b.zip", data: "..." })
+      def upload(body_params = nil, options = {})
+        opts = send_options({ method: "POST", body: body_params }, options)
+        @client.send_request("/api/backups/upload", opts)
+        true
+      end
+
+      # Deletes a single backup file. Returns true.
+      def delete(key, options = {})
+        opts = send_options({ method: "DELETE" }, options)
+        @client.send_request("/api/backups/#{Utils.encode_uri_component(key.to_s)}", opts)
+        true
+      end
+
+      # Initializes an app data restore from an existing backup. Returns true.
+      def restore(key, options = {})
+        opts = send_options({ method: "POST" }, options)
+        @client.send_request("/api/backups/#{Utils.encode_uri_component(key.to_s)}/restore", opts)
+        true
+      end
+
+      # Builds a download URL for a backup using a file token
+      # (generate one via pb.files.get_token).
+      def get_download_url(token, key)
+        @client.build_url(
+          "/api/backups/#{Utils.encode_uri_component(key.to_s)}" \
+          "?token=#{Utils.encode_uri_component(token.to_s)}"
+        )
+      end
+    end
+  end
+end