databasus_ruby 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9223ce08d06f8a4f29e700d9046bab99ee5aaec01131af37a12620cdec27b7ed
-  data.tar.gz: 1cd2c4226183d6106dd8a351e61533c2bdf513f818bb0e43f4c3dd077fe548b0
+  metadata.gz: c06a2f99b31ebac53becd79a06a01790a65e106890f2275f0645548197c33611
+  data.tar.gz: 14433d80684697a781025fb4dce7f0839fe5448dbc6cbef9f7c52e257b52c8b9
 SHA512:
-  metadata.gz: f4c7dda68f74e63dc5833e41b2aff40c730f5462920bc8aaee57549a0b435516d187d07bd6e62591d7ef10b03f863d2492d5754da422021089bcaa4226d26fe2
-  data.tar.gz: 5c59d0c7e223f8904a54de677f5083c9cd94466e16e60d082b02ef42124784e52f28c09922fbe33542bf5e7b5f5c07c3b2e7a21a5d675e96e46cda29715ba7e7
+  metadata.gz: 25a821696e164674b457941926ae8940ac8656af9106409fe9d63c7c2bb2f429805e52ab057725876f8e57697566d6327a4fe0b55604342cd9ac3793939953c1
+  data.tar.gz: a2b67bc8e87d04c3306b4c1198f4352f7cdd2f5af7177c456df0e5c23c46d808a38f17aa35ab1875b2cd5db281c4c4718193f14225ed4265347b6189cc4fcf06

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-13
+
+Targets the REST API of Databasus 3.65 and later. Databasus 3.65 replaced its
+API (new paths, cursor pagination, RFC 9457 problem responses), so this release
+does not talk to 3.64 or earlier: pin `~> 0.1.0` for those.
+
+### Added
+
+- `Restores` endpoint (`start`, `get`, `list`, `cancel`) and
+  `Restores.postgresql_target`, which restores without ownership and
+  privileges by default.
+- `Backups#download_to(id, io)` and `Client#stream`: backups stream to an IO
+  instead of being read into memory.
+- `Backups#get`; `Databases#list_all`, which follows the cursor; `Databases#test`
+  / `#connected?`; `Storages#backup_usage`; `Auth#verify_sign_in_code`.
+- `APIError#code` (the problem's `code`); validation field errors are appended
+  to the message.
+- `SignInCodeRequiredError`, raised by `Auth#signin` when the account needs an
+  emailed sign-in code.
+- `Collection#next_cursor`, `#last_page?` and `#extras` (page-level fields such
+  as the backups page's `totalUsageMb`).
+
+### Changed
+
+- Every path follows the 3.65 API: `POST /sessions`, `/logical-backups`,
+  `POST /download-tokens`, `PUT /databases/{id}`, `/workspace-members`,
+  `/audit-events`, `/instance-settings`, `/password-resets`.
+- List methods take `limit:` / `after:` instead of `limit:` / `offset:`.
+- Array query parameters repeat the key (`status=A&status=B`).
+- `Notifiers` and `Storages` split `save` into `create` and `update(id, ...)`.
+- Renamed: `Auth#send_reset_password_code` → `#request_password_reset`,
+  `Databases#test_connection` → `#test`, `Workspaces#audit_logs` → `#audit_events` (filter with `author_user_id:`).
+- Methods now take the target id positionally: `Databases#update(id, ...)`,
+  `Users#update(id, name:, email:)`, `Users#change_password(id, new_password:)`,
+  `Workspaces#update(id, name:)`.
+- Workspace membership is addressed by member id: `remove_member(member_id)`,
+  `change_member_role(member_id, role:)`, and
+  `transfer_ownership(id, new_owner_member_id:)` replaces `new_owner_email:`.
+- `Backups#list` filters with `created_before:` (was `before_date:`);
+  `Databases#list` accepts `notifier_id:`.
+- `APIError` messages come from the problem's `detail` / `title`;
+  `APIError.from_response` accepts a `body:` override for streamed responses.
+- JSON responses are parsed for any `*json*` content type
+  (e.g. `application/problem+json`).
+
+### Removed
+
+- Offset pagination (`Collection#total`, `#limit`, `#offset`, `#next_offset`).
+- Endpoints the API dropped: OAuth callbacks (`Auth#github_callback`,
+  `#google_callback`), `Users#me`, `#update_me`, `#invite`, readonly and
+  replication users (`Databases#create_readonly_user`,
+  `#create_replication_only_user`, `#readonly`, `#readonly?`), `Databases#test_connection_direct`,
+  notifier usage counts (`Databases#notifier_databases_count`,
+  `#notifier_using?`), and the `direct_test` methods of `Notifiers` and
+  `Storages`.
+
+## [0.1.0]
+
 ### Added
 
 - `DatabasusRuby::Client` with bearer authentication, an optional default

data/README.md

@@ -109,10 +109,18 @@ A database can reach its own backups, which delegates to the `backups` endpoint
 with the same filters as `client.backups.list`:
 
 ```ruby
+database.backups(status: "COMPLETED", limit: 25)
+database.backup                                    # queue a run
+
+# or by id, from the endpoint
 client.databases.backups(database.id, status: "COMPLETED", limit: 25)
-client.databases.backup(database.id)               # queue a run
+client.databases.backup(database.id)
 ```
 
+`list`, `get`, `create`, `update` and `copy` return `DatabasusRuby::Database`
+records: payload objects that read exactly like any other response but also
+carry the two methods above.
+
 `update` posts to `/databases/update` with the id in the body, matching the API.
 There is also `test_connection_direct`, `create_readonly_user`,
 `create_replication_only_user` and `readonly?` for a payload you have not saved

data/lib/databasus_ruby/client.rb

@@ -4,16 +4,14 @@ module DatabasusRuby
   # Entry point for the gem. Holds the connection and hands out one endpoint
   # object per API domain.
   #
-  #   client = DatabasusRuby::Client.new(
-  #     api_key: ENV["DATABASUS_API_KEY"],
-  #     url: "https://databasus.example.com/api/v1/"
-  #   )
+  #   client = DatabasusRuby::Client.new(url: "https://databasus.example.com/api/v1/")
+  #   client.auth.signin(email: "ops@example.com", password: "secret")
   #   client.databases.list(workspace_id: id)
   #
-  # `api_key` is sent as `Authorization: Bearer <api_key>`. Databasus accepts
-  # two kinds of bearer token there: a user JWT (from Auth#signin, used by
-  # every regular endpoint) and a verification-agent token (used by the
-  # /agent/* endpoints, which also need `agent_id`).
+  # Targets the Databasus REST API introduced in 3.65 (OpenAPI, cursor
+  # pagination, RFC 9457 problem responses). `api_key` is sent as
+  # `Authorization: Bearer <api_key>`; Auth#signin installs the session token
+  # there.
   class Client
     attr_reader :adapter, :url
     attr_accessor :api_key, :workspace_id
@@ -30,8 +28,11 @@ module DatabasusRuby
     def connection
       @connection ||= Faraday.new do |conn|
         conn.url_prefix = url
+        # Array filters (`status=A&status=B`) are form-style with explode,
+        # which the nested encoder would send as `status[]=`.
+        conn.options.params_encoder = Faraday::FlatParamsEncoder
         conn.request :json
-        conn.response :json, content_type: "application/json"
+        conn.response :json, content_type: /\bjson\b/
         conn.adapter adapter
       end
     end
@@ -52,6 +53,10 @@ module DatabasusRuby
       @notifiers ||= Notifiers.new(self)
     end
 
+    def restores
+      @restores ||= Restores.new(self)
+    end
+
     def storages
       @storages ||= Storages.new(self)
     end
@@ -64,8 +69,8 @@ module DatabasusRuby
       @workspaces ||= Workspaces.new(self)
     end
 
-    # The workspace-scoped list endpoints all require a workspace id; callers
-    # can either pass one per call or set a default on the client.
+    # The workspace-scoped list endpoints filter by workspace; callers can
+    # either pass one per call or set a default on the client.
     def workspace_id!
       return workspace_id unless workspace_id.nil? || workspace_id.to_s.empty?
 
@@ -78,9 +83,8 @@ module DatabasusRuby
     # decide how to interpret the body.
     def request(method, path, params: nil, body: nil, headers: nil)
       response = connection.public_send(method, path) do |req|
-        req.params.update(stringify(params)) if params
+        prepare(req, params: params, headers: headers)
         req.body = body unless body.nil?
-        req.headers.update(request_headers(headers))
       end
 
       raise APIError.from_response(response) unless response.success?
@@ -88,15 +92,67 @@ module DatabasusRuby
       response
     end
 
+    # GETs `path` and writes the body to `io` chunk by chunk, so a multi-GB
+    # backup never sits in memory. An error answer is collected instead and
+    # raised as the matching APIError. Returns the number of bytes written.
+    def stream(path, io:, params: nil)
+      sink = StreamSink.new(io)
+      response = connection.get(path) do |req|
+        prepare(req, params: params)
+        # Faraday streams only when on_data is a Proc (RequestOptions#stream_response?).
+        req.options.on_data = sink.to_proc
+      end
+      return sink.written if response.success?
+
+      raise APIError.from_response(response, body: sink.decoded_error_body)
+    end
+
+    # Routes streamed chunks: a 2xx body goes to the caller's io, anything else
+    # is kept so it can be raised as an APIError.
+    class StreamSink
+      attr_reader :written, :error_body
+
+      def initialize(io)
+        @io = io
+        @written = 0
+        @error_body = +""
+      end
+
+      def to_proc
+        proc { |chunk, _received, env| write(chunk, env) }
+      end
+
+      def decoded_error_body
+        return nil if error_body.empty?
+
+        JSON.parse(error_body)
+      rescue JSON::ParserError
+        error_body
+      end
+
+      private
+
+      def write(chunk, env)
+        return @error_body << chunk unless env.nil? || (200..299).cover?(env.status)
+
+        @io.write(chunk)
+        @written += chunk.bytesize
+      end
+    end
+    private_constant :StreamSink
+
     def inspect
-      "#<#{self.class.name} url=#{url.inspect} workspace_id=#{workspace_id.inspect}\
-      api_key=#{api_key.nil? ? "nil" : "[FILTERED]"}>"
+      "#<#{self.class.name} url=#{url.inspect} workspace_id=#{workspace_id.inspect} " \
+        "api_key=#{api_key.nil? ? "nil" : "[FILTERED]"}>"
     end
 
     private
 
-    # Databasus takes the token as a bearer credential; both a user JWT and a
-    # verification-agent token go in the same header.
+    def prepare(req, params: nil, headers: nil)
+      req.params.update(stringify(params)) if params
+      req.headers.update(request_headers(headers))
+    end
+
     def request_headers(extra)
       headers = {}
       headers["Authorization"] = "Bearer #{api_key}" unless api_key.nil? || api_key.to_s.empty?
@@ -110,13 +166,12 @@ module DatabasusRuby
       url.to_s.end_with?("/") ? url.to_s : "#{url}/"
     end
 
+    # Drops nils; arrays stay arrays so FlatParamsEncoder repeats the key.
     def stringify(params)
       params.each_with_object({}) do |(key, value), acc|
         next if value.nil?
 
-        # The only array-valued query parameter in the API (backups status)
-        # is declared as collectionFormat: csv.
-        acc[key.to_s] = value.is_a?(::Array) ? value.join(",") : value
+        acc[key.to_s] = value.is_a?(::Array) ? value.map(&:to_s) : value
       end
     end
   end

data/lib/databasus_ruby/collection.rb

@@ -3,38 +3,44 @@
 module DatabasusRuby
   # Uniform return value for every list endpoint.
   #
-  # Databasus answers lists in three different shapes: a bare array
-  # (GET /databases), a paginated envelope (GET /backups) and an unpaginated
-  # envelope (GET /workspaces). Collection flattens all three into an
-  # Enumerable that always answers #total, and answers #limit / #offset when
-  # the endpoint actually paginates.
+  # Databasus answers every list as a cursor page: `{ items: [...],
+  # nextCursor: "..." }`, plus page-level extras on some endpoints (the logical
+  # backups page carries `totalUsageMb`). Pass #next_cursor back as `after:` to
+  # read the next page; it is nil on the last one.
+  #
+  #   page = client.backups.list(database_id: id, limit: 50)
+  #   page.extras.total_usage_mb
+  #   page.next_cursor
   class Collection
     include Enumerable
 
-    attr_reader :data, :total, :limit, :offset
+    attr_reader :data, :next_cursor, :extras
 
-    def initialize(data: [], total: nil, limit: nil, offset: nil)
-      @data = data.map { |item| item.is_a?(Object) ? item : Object.new(item) }
-      @total = total || @data.size
-      @limit = limit
-      @offset = offset
+    # `wrap` builds one entry from its raw hash; it defaults to a plain Object
+    # and endpoints pass a Record builder instead.
+    def initialize(data: [], next_cursor: nil, extras: {}, wrap: nil)
+      @data = data.map { |item| item.is_a?(Object) ? item : (wrap || Object.method(:new)).call(item) }
+      @next_cursor = next_cursor
+      @extras = extras.is_a?(Object) ? extras : Object.new(extras)
     end
 
-    # `key` names the array inside an envelope response and is ignored for
-    # bare-array responses.
-    def self.from(body, key:)
+    PAGE_KEYS = %w[items nextCursor].freeze
+
+    def self.from(body, wrap: nil)
       case body
-      when ::Array
-        new(data: body)
-      when Hash
-        new(data: body[key] || [], total: body["total"], limit: body["limit"], offset: body["offset"])
-      when nil
-        new
-      else
-        raise Error, "unexpected list payload: #{body.class}"
+      when Hash then from_page(body, wrap)
+      when ::Array then new(data: body, wrap: wrap)
+      when nil, "" then new
+      else raise Error, "unexpected list payload: #{body.class}"
       end
     end
 
+    def self.from_page(page, wrap)
+      extras = page.reject { |key, _| PAGE_KEYS.include?(key.to_s) }
+      new(data: page["items"] || [], next_cursor: page["nextCursor"], extras: extras, wrap: wrap)
+    end
+    private_class_method :from_page
+
     def each(&block)
       return data.each unless block
 
@@ -59,25 +65,12 @@ module DatabasusRuby
       data.last
     end
 
-    def paginated?
-      !limit.nil?
-    end
-
-    # Offset to pass to the next call, or nil when this is the last page (or
-    # the endpoint does not paginate at all).
-    def next_offset
-      return nil unless paginated?
-
-      following = (offset || 0) + data.size
-      following < total ? following : nil
-    end
-
     def last_page?
-      next_offset.nil?
+      next_cursor.nil? || next_cursor.to_s.empty?
     end
 
     def inspect
-      "#<#{self.class.name} size=#{size} total=#{total} limit=#{limit.inspect} offset=#{offset.inspect}>"
+      "#<#{self.class.name} size=#{size} next_cursor=#{next_cursor.inspect}>"
     end
   end
 end

data/lib/databasus_ruby/endpoint.rb

@@ -43,14 +43,21 @@ module DatabasusRuby
       client.request(:delete, path, params: params)
     end
 
-    # Wraps a single-object response.
-    def object(response)
-      Object.new(response.body.is_a?(Hash) ? response.body : {})
+    # Wraps a single-object response. `as` names a Record subclass for the
+    # domains whose payloads carry methods of their own.
+    def object(response, as: Object)
+      build(as, response.body.is_a?(Hash) ? response.body : {})
     end
 
-    # Wraps a list response; `key` names the array inside an envelope payload.
-    def collection(response, key:)
-      Collection.from(response.body, key: key)
+    # Wraps a cursor-page list response.
+    def collection(response, as: Object)
+      Collection.from(response.body, wrap: ->(item) { build(as, item) })
+    end
+
+    # Records need the client to reach their related endpoints; plain payload
+    # objects do not.
+    def build(klass, attributes)
+      klass <= Record ? klass.new(client, attributes) : klass.new(attributes)
     end
 
     # For endpoints that answer 200/204 with no meaningful body.
@@ -58,13 +65,6 @@ module DatabasusRuby
       true
     end
 
-    # Endpoints answering a single-entry map whose key is not documented in the
-    # swagger schema, e.g. GET /databases/notifier/{id}/is-using.
-    def single_value(response)
-      body = response.body
-      body.is_a?(Hash) ? body.values.first : body
-    end
-
     # Request bodies are built from keyword arguments, and the API distinguishes
     # an absent key from a null one in a few places, so nils are dropped.
     def compact(body)

data/lib/databasus_ruby/error.rb

@@ -5,24 +5,44 @@ module DatabasusRuby
   class Error < StandardError; end
 
   # Raised when the client is missing something it needs before it can talk to
-  # the API at all (an agent id, a workspace id, ...).
+  # the API at all (a workspace id, a url, ...).
   class ConfigurationError < Error; end
 
+  # Raised by Auth#signin when the account requires an emailed sign-in code
+  # (two-factor). An unattended client cannot answer it; use an account
+  # without 2FA or finish with Auth#verify_sign_in_code.
+  class SignInCodeRequiredError < Error
+    attr_reader :pending_sign_in_id, :email
+
+    def initialize(pending_sign_in_id:, email:)
+      @pending_sign_in_id = pending_sign_in_id
+      @email = email
+      super("sign-in for #{email} needs the emailed code (pending sign-in #{pending_sign_in_id})")
+    end
+  end
+
   # Raised when Databasus answers with a non-successful status code.
+  #
+  # Databasus answers errors as RFC 9457 problems:
+  # `{ type, title, status, detail, code, errors }`. `code` is the stable
+  # machine-readable reason (`database_connection_failed`,
+  # `insufficient_disk_space`, `already_running`, ...).
   class APIError < Error
-    attr_reader :status, :body, :response
+    attr_reader :status, :body, :response, :code
 
-    def initialize(message = nil, status: nil, body: nil, response: nil)
+    def initialize(message = nil, status: nil, body: nil, response: nil, code: nil)
       @status = status
       @body = body
       @response = response
+      @code = code
       super(message || "Databasus API returned #{status}")
     end
 
     # Maps a Faraday response onto the most specific error class available.
-    def self.from_response(response)
+    # `body` overrides the response body (streamed responses carry none).
+    def self.from_response(response, body: response.body)
       klass = for_status(response.status)
-      klass.new(message_from(response.body), status: response.status, body: response.body, response: response)
+      klass.new(message_from(body), status: response.status, body: body, response: response, code: code_from(body))
     end
 
     def self.for_status(status)
@@ -31,15 +51,25 @@ module DatabasusRuby
       STATUS_ERRORS.fetch(status, APIError)
     end
 
-    # Every handler in the Go backend answers errors as {"error": "..."}, but
-    # streaming endpoints can still fail with a plain-text body.
+    # A validation problem's `detail` is generic ("the request breaks a
+    # validation rule"); the field errors are what say which rule.
     def self.message_from(body)
       case body
-      when Hash then body["error"] || body["message"] || body[:error]
+      when Hash then problem_message(body)
       when String then body.empty? ? nil : body[0, 500]
       end
     end
-    private_class_method :message_from
+
+    def self.problem_message(problem)
+      message = problem["detail"] || problem["title"] || problem["error"] || problem["message"]
+      fields = Array(problem["errors"]).filter_map { |e| "#{e["field"]}: #{e["detail"]}" if e.is_a?(Hash) }
+      fields.empty? ? message : [message, fields.join("; ")].compact.join(" — ")
+    end
+
+    def self.code_from(body)
+      body["code"] if body.is_a?(Hash)
+    end
+    private_class_method :message_from, :problem_message, :code_from
   end
 
   class BadRequestError < APIError; end

data/lib/databasus_ruby/objects/auth.rb

@@ -1,28 +1,46 @@
 # frozen_string_literal: true
 
 module DatabasusRuby
-  # Obtaining a token. Every other endpoint needs the JWT these methods
-  # return, so #signin and #signup install it on the client as `api_key`.
+  # Obtaining a session token. Every other endpoint needs the token these
+  # methods return, so a completed sign-in installs it on the client as
+  # `api_key`.
   #
   #   client.auth.signin(email: "me@example.com", password: "secret")
-  #   client.users.me.name
+  #   client.databases.list(workspace_id: id)
   #
-  # Read the token off the result if you want to keep it for a later client.
+  # An account with two-factor sign-in answers CODE_REQUIRED: #signin raises
+  # SignInCodeRequiredError and #verify_sign_in_code finishes it.
   class Auth < Object
     include Endpoint
 
-    # POST /users/signin
+    # POST /sessions
+    #
+    # @return [DatabasusRuby::Object] the completed sign-in (`token`, `userId`, `email`)
+    # @raise [DatabasusRuby::SignInCodeRequiredError] when the account needs the emailed code
     def signin(email:, password:, cloudflare_turnstile_token: nil)
-      authorize object(http_post("users/signin", {
+      outcome = object(http_post("sessions", {
                                    email: email,
                                    password: password,
                                    cloudflareTurnstileToken: cloudflare_turnstile_token
                                  }))
+      if outcome.outcome == "CODE_REQUIRED"
+        raise SignInCodeRequiredError.new(pending_sign_in_id: outcome.pending_sign_in_id, email: outcome.email)
+      end
+
+      authorize outcome
+    end
+
+    # POST /pending-sign-ins/{id}/verify
+    def verify_sign_in_code(pending_sign_in_id, code:, cloudflare_turnstile_token: nil)
+      authorize object(http_post("pending-sign-ins/#{escape(pending_sign_in_id)}/verify", {
+                                   code: code,
+                                   cloudflareTurnstileToken: cloudflare_turnstile_token
+                                 }))
     end
 
-    # POST /users/signup
+    # POST /users — self-registration, when the instance allows it.
     def signup(email:, name:, password:, cloudflare_turnstile_token: nil)
-      authorize object(http_post("users/signup", {
+      authorize object(http_post("users", {
                                    email: email,
                                    name: name,
                                    password: password,
@@ -30,27 +48,14 @@ module DatabasusRuby
                                  }))
     end
 
-    # POST /auth/github/callback
-    def github_callback(code:, redirect_uri:)
-      object(http_post("auth/github/callback", { code: code, redirectUri: redirect_uri }))
-    end
-
-    # POST /auth/google/callback
-    def google_callback(code:, redirect_uri:)
-      object(http_post("auth/google/callback", { code: code, redirectUri: redirect_uri }))
-    end
-
-    # POST /users/send-reset-password-code
-    def send_reset_password_code(email:, cloudflare_turnstile_token: nil)
-      object(http_post("users/send-reset-password-code", {
-                         email: email,
-                         cloudflareTurnstileToken: cloudflare_turnstile_token
-                       }))
+    # POST /password-resets — emails a reset code.
+    def request_password_reset(email:, cloudflare_turnstile_token: nil)
+      acknowledged(http_post("password-resets", { email: email, cloudflareTurnstileToken: cloudflare_turnstile_token }))
     end
 
-    # POST /users/reset-password
+    # POST /password-reset-completions
     def reset_password(email:, code:, new_password:)
-      object(http_post("users/reset-password", { email: email, code: code, newPassword: new_password }))
+      acknowledged(http_post("password-reset-completions", { email: email, code: code, newPassword: new_password }))
     end
 
     private