databasus_ruby 0.0.1

data/lib/databasus_ruby/error.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Base class for every error raised by this gem.
+  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, ...).
+  class ConfigurationError < Error; end
+
+  # Raised when Databasus answers with a non-successful status code.
+  class APIError < Error
+    attr_reader :status, :body, :response
+
+    def initialize(message = nil, status: nil, body: nil, response: nil)
+      @status = status
+      @body = body
+      @response = response
+      super(message || "Databasus API returned #{status}")
+    end
+
+    # Maps a Faraday response onto the most specific error class available.
+    def self.from_response(response)
+      klass = for_status(response.status)
+      klass.new(message_from(response.body), status: response.status, body: response.body, response: response)
+    end
+
+    def self.for_status(status)
+      return ServerError if (500..599).cover?(status)
+
+      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.
+    def self.message_from(body)
+      case body
+      when Hash then body["error"] || body["message"] || body[:error]
+      when String then body.empty? ? nil : body[0, 500]
+      end
+    end
+    private_class_method :message_from
+  end
+
+  class BadRequestError < APIError; end
+  class AuthenticationError < APIError; end
+  class ForbiddenError < APIError; end
+  class NotFoundError < APIError; end
+  class ConflictError < APIError; end
+  class RateLimitError < APIError; end
+  class ServerError < APIError; end
+
+  class APIError
+    STATUS_ERRORS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      429 => RateLimitError
+    }.freeze
+  end
+end

data/lib/databasus_ruby/object.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # A thin, duck-typed wrapper around a decoded JSON payload.
+  #
+  #   database = client.databases.get(id)
+  #   database.name                 # => "primary"
+  #   database.workspace_id         # => same as database.workspaceId
+  #   database.postgresqlLogical.host
+  #
+  # Nested hashes (and arrays of hashes) are wrapped on access, so the whole
+  # tree reads the same way. The Databasus API omits empty fields, so reading a
+  # key that is not in the payload returns nil rather than raising.
+  class Object
+    def initialize(attributes = {})
+      @attributes = normalize(attributes)
+    end
+
+    def to_h
+      @attributes
+    end
+    alias to_hash to_h
+
+    def [](key)
+      fetch_attribute(key.to_s)
+    end
+
+    def key?(key)
+      return false if @attributes.nil?
+
+      @attributes.key?(key.to_s) || @attributes.key?(camelize(key.to_s))
+    end
+    alias has_key? key?
+
+    def keys
+      @attributes.nil? ? [] : @attributes.keys
+    end
+
+    def ==(other)
+      other.is_a?(Object) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{keys.join(", ")}>"
+    end
+
+    def method_missing(name, *args, &block)
+      # Endpoint classes inherit from Object without carrying a payload; for
+      # them an unknown method is a genuine mistake, not a missing field.
+      return super if @attributes.nil?
+      return super unless args.empty? && block.nil?
+
+      fetch_attribute(name.to_s)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @attributes.nil? ? super : true
+    end
+
+    private
+
+    def normalize(attributes)
+      return nil if attributes.nil?
+      return attributes.to_h.transform_keys(&:to_s) if attributes.respond_to?(:to_h)
+
+      raise ArgumentError, "expected a Hash-like payload, got #{attributes.class}"
+    end
+
+    def fetch_attribute(key)
+      raw = if @attributes.key?(key)
+              @attributes[key]
+            else
+              @attributes[camelize(key)]
+            end
+      wrap(raw)
+    end
+
+    def wrap(value)
+      case value
+      when Hash then Object.new(value)
+      when ::Array then value.map { |item| wrap(item) }
+      else value
+      end
+    end
+
+    # workspace_id -> workspaceId, so Ruby callers can stay in snake_case.
+    def camelize(key)
+      head, *rest = key.split("_")
+      return key if rest.empty?
+
+      head + rest.map(&:capitalize).join
+    end
+  end
+end

data/lib/databasus_ruby/objects/auth.rb

@@ -0,0 +1,66 @@
+# 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`.
+  #
+  #   client.auth.signin(email: "me@example.com", password: "secret")
+  #   client.users.me.name
+  #
+  # Read the token off the result if you want to keep it for a later client.
+  class Auth < Object
+    include Endpoint
+
+    # POST /users/signin
+    def signin(email:, password:, cloudflare_turnstile_token: nil)
+      authorize object(http_post("users/signin", {
+                                   email: email,
+                                   password: password,
+                                   cloudflareTurnstileToken: cloudflare_turnstile_token
+                                 }))
+    end
+
+    # POST /users/signup
+    def signup(email:, name:, password:, cloudflare_turnstile_token: nil)
+      authorize object(http_post("users/signup", {
+                                   email: email,
+                                   name: name,
+                                   password: password,
+                                   cloudflareTurnstileToken: cloudflare_turnstile_token
+                                 }))
+    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
+                       }))
+    end
+
+    # POST /users/reset-password
+    def reset_password(email:, code:, new_password:)
+      object(http_post("users/reset-password", { email: email, code: code, newPassword: new_password }))
+    end
+
+    private
+
+    def authorize(result)
+      token = result.token
+      raise Error, "Databasus did not return a token" if token.nil? || token.empty?
+
+      client.api_key = token
+      result
+    end
+  end
+end

data/lib/databasus_ruby/objects/backups.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Logical backups.
+  #
+  #   backups = client.backups.list(database_id: id, status: %w[COMPLETED FAILED])
+  #   backups.total
+  #   backups.first.fileName
+  #
+  # Downloads are a two-step flow: mint a short-lived token, then stream the
+  # file with it. #download does both.
+  class Backups < Object
+    include Endpoint
+
+    STATUSES = %w[IN_PROGRESS COMPLETED FAILED CANCELED].freeze
+    ENCRYPTIONS = %w[NONE ENCRYPTED].freeze
+    VERIFICATION_STATUSES = %w[NOT_VERIFIED VERIFIED_SUCCESSFUL VERIFICATION_FAILED].freeze
+
+    # GET /backups — `status` accepts a single value or an array.
+    def list(database_id:, limit: nil, offset: nil, status: nil, before_date: nil, pg_wal_backup_type: nil)
+      response = http_get("backups", {
+                            database_id: database_id,
+                            limit: limit,
+                            offset: offset,
+                            status: status,
+                            beforeDate: before_date,
+                            pgWalBackupType: pg_wal_backup_type
+                          })
+      collection(response, key: "backups")
+    end
+    alias all list
+
+    # POST /backups — queues a backup run for the database.
+    def create(database_id:)
+      object(http_post("backups", { database_id: database_id }))
+    end
+    alias trigger create
+
+    # DELETE /backups/{id}
+    def delete(id)
+      acknowledged(http_delete("backups/#{escape(id)}"))
+    end
+
+    # POST /backups/{id}/cancel
+    def cancel(id)
+      acknowledged(http_post("backups/#{escape(id)}/cancel"))
+    end
+
+    # POST /backups/{id}/download-token -> { token, filename, backupId }
+    def download_token(id)
+      object(http_post("backups/#{escape(id)}/download-token"))
+    end
+
+    # GET /backups/{id}/file — returns the raw body; pass a token from
+    # #download_token.
+    def file(id, token:)
+      http_get("backups/#{escape(id)}/file", { token: token }).body
+    end
+
+    # Mints a token and fetches the file in one call. Returns
+    # [filename, contents].
+    def download(id)
+      grant = download_token(id)
+      [grant.filename, file(id, token: grant.token)]
+    end
+  end
+end

data/lib/databasus_ruby/objects/databases.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Databases under backup.
+  #
+  #   client.databases.list(workspace_id: id)
+  #   client.databases.create(name: "primary", type: "POSTGRES_LOGICAL",
+  #                           workspaceId: id, postgresqlLogical: { ... })
+  #
+  # The create/update bodies are the full databases.Database payload, whose
+  # engine-specific half lives under one of `postgresqlLogical`,
+  # `postgresqlPhysical`, `mysql`, `mariadb` or `mongodb`.
+  class Databases < Object
+    include Endpoint
+
+    TYPES = %w[POSTGRES_LOGICAL POSTGRES_PHYSICAL MYSQL MARIADB MONGODB].freeze
+    HEALTH_STATUSES = %w[AVAILABLE UNAVAILABLE].freeze
+
+    # GET /databases
+    def list(workspace_id: nil)
+      collection(http_get("databases", { workspace_id: workspace_id || client.workspace_id! }), key: "databases")
+    end
+    alias all list
+
+    # GET /databases/{id}
+    def get(id)
+      object(http_get("databases/#{escape(id)}"))
+    end
+    alias find get
+
+    # POST /databases/create
+    def create(**attributes)
+      object(http_post("databases/create", with_default_workspace(attributes)))
+    end
+
+    # POST /databases/update — the id travels in the body, not the path.
+    def update(**attributes)
+      object(http_post("databases/update", attributes))
+    end
+
+    # DELETE /databases/{id}
+    def delete(id)
+      acknowledged(http_delete("databases/#{escape(id)}"))
+    end
+
+    # POST /databases/{id}/copy
+    def copy(id)
+      object(http_post("databases/#{escape(id)}/copy"))
+    end
+
+    # POST /databases/{id}/test-connection — true when the database answers.
+    def test_connection(id)
+      acknowledged(http_post("databases/#{escape(id)}/test-connection"))
+    end
+
+    # POST /databases/test-connection-direct — tests a payload that has not
+    # been saved yet.
+    def test_connection_direct(**attributes)
+      acknowledged(http_post("databases/test-connection-direct", attributes))
+    end
+
+    # POST /databases/create-readonly-user -> { username, password }
+    def create_readonly_user(**attributes)
+      object(http_post("databases/create-readonly-user", attributes))
+    end
+
+    # POST /databases/create-replication-only-user (PostgreSQL physical only)
+    def create_replication_only_user(**attributes)
+      object(http_post("databases/create-replication-only-user", attributes))
+    end
+
+    # POST /databases/is-readonly -> { isReadOnly, privileges }
+    def readonly(**attributes)
+      object(http_post("databases/is-readonly", attributes))
+    end
+
+    def readonly?(**attributes)
+      readonly(**attributes).isReadOnly == true
+    end
+
+    # The backups of one database, so a caller holding a database does not have
+    # to reach back for the other endpoint. Both delegate to Backups, which
+    # owns the requests.
+    #
+    #   client.databases.backups(database.id, status: "COMPLETED")
+    #   client.databases.backup(database.id)          # queue a run
+    #
+    # #backups takes the same filters as Backups#list.
+    def backups(id, **filters)
+      client.backups.list(database_id: require_id(id), **filters)
+    end
+
+    def backup(id)
+      client.backups.create(database_id: require_id(id))
+    end
+
+    # GET /databases/notifier/{id}/databases-count
+    def notifier_databases_count(notifier_id)
+      single_value(http_get("databases/notifier/#{escape(notifier_id)}/databases-count"))
+    end
+
+    # GET /databases/notifier/{id}/is-using
+    def notifier_using?(notifier_id)
+      single_value(http_get("databases/notifier/#{escape(notifier_id)}/is-using")) == true
+    end
+  end
+end

data/lib/databasus_ruby/objects/notifiers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Notification channels.
+  #
+  #   client.notifiers.save(name: "ops", notifierType: "SLACK",
+  #                         workspaceId: id, slackNotifier: { ... })
+  #
+  # POST /notifiers both creates and updates: include `id` in the payload to
+  # update an existing notifier.
+  class Notifiers < Object
+    include Endpoint
+
+    TYPES = %w[EMAIL TELEGRAM WEBHOOK SLACK DISCORD TEAMS].freeze
+    NOTIFICATION_TYPES = %w[
+      ALL BACKUP_SUCCESS BACKUP_FAILED HEALTHCHECK_SUCCESS HEALTHCHECK_FAILED
+      VERIFICATION_SUCCESS VERIFICATION_FAILED
+    ].freeze
+
+    # GET /notifiers
+    def list(workspace_id: nil)
+      collection(http_get("notifiers", { workspace_id: workspace_id || client.workspace_id! }), key: "notifiers")
+    end
+    alias all list
+
+    # GET /notifiers/{id}
+    def get(id)
+      object(http_get("notifiers/#{escape(id)}"))
+    end
+    alias find get
+
+    # POST /notifiers
+    def save(**attributes)
+      object(http_post("notifiers", with_default_workspace(attributes)))
+    end
+    alias create save
+    alias update save
+
+    # DELETE /notifiers/{id}
+    def delete(id)
+      acknowledged(http_delete("notifiers/#{escape(id)}"))
+    end
+
+    # POST /notifiers/{id}/test — sends a test notification.
+    def test(id)
+      acknowledged(http_post("notifiers/#{escape(id)}/test"))
+    end
+
+    # POST /notifiers/direct-test — tests a payload that has not been saved yet.
+    def direct_test(**attributes)
+      acknowledged(http_post("notifiers/direct-test", attributes))
+    end
+
+    # POST /notifiers/{id}/transfer
+    def transfer(id, target_workspace_id:)
+      acknowledged(http_post("notifiers/#{escape(id)}/transfer", { targetWorkspaceId: target_workspace_id }))
+    end
+  end
+end

data/lib/databasus_ruby/objects/storages.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Backup destinations.
+  #
+  #   client.storages.save(name: "offsite", type: "S3",
+  #                        workspaceId: id, s3Storage: { ... })
+  #
+  # POST /storages both creates and updates: include `id` in the payload to
+  # update an existing storage.
+  class Storages < Object
+    include Endpoint
+
+    TYPES = %w[LOCAL S3 GOOGLE_DRIVE NAS AZURE_BLOB FTP SFTP RCLONE].freeze
+
+    # GET /storages
+    def list(workspace_id: nil)
+      collection(http_get("storages", { workspace_id: workspace_id || client.workspace_id! }), key: "storages")
+    end
+    alias all list
+
+    # GET /storages/{id}
+    def get(id)
+      object(http_get("storages/#{escape(id)}"))
+    end
+    alias find get
+
+    # POST /storages
+    def save(**attributes)
+      object(http_post("storages", with_default_workspace(attributes)))
+    end
+    alias create save
+    alias update save
+
+    # DELETE /storages/{id}
+    def delete(id)
+      acknowledged(http_delete("storages/#{escape(id)}"))
+    end
+
+    # POST /storages/{id}/test
+    def test(id)
+      acknowledged(http_post("storages/#{escape(id)}/test"))
+    end
+
+    # POST /storages/direct-test — tests a payload that has not been saved yet.
+    def direct_test(**attributes)
+      acknowledged(http_post("storages/direct-test", attributes))
+    end
+
+    # POST /storages/{id}/transfer
+    def transfer(id, target_workspace_id:)
+      acknowledged(http_post("storages/#{escape(id)}/transfer", { targetWorkspaceId: target_workspace_id }))
+    end
+  end
+end

data/lib/databasus_ruby/objects/users.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # The signed-in user, instance-wide user administration and instance
+  # settings.
+  #
+  #   client.users.me.email
+  #   client.users.list(query: "ops", limit: 25).each { |user| ... }
+  #
+  # The #list / #get / #activate / #deactivate / #change_role and settings
+  # methods are ADMIN-only and answer 403 for a MEMBER token.
+  class Users < Object
+    include Endpoint
+
+    ROLES = %w[ADMIN MEMBER].freeze
+
+    # GET /users/me
+    def me
+      object(http_get("users/me"))
+    end
+
+    # PUT /users/me
+    def update_me(name: nil, email: nil)
+      object(http_put("users/me", { name: name, email: email }))
+    end
+
+    # PUT /users/change-password
+    def change_password(new_password:)
+      object(http_put("users/change-password", { newPassword: new_password }))
+    end
+
+    # POST /users/invite
+    def invite(email:, intended_workspace_id: nil, intended_workspace_role: nil)
+      object(http_post("users/invite", {
+                         email: email,
+                         intendedWorkspaceId: intended_workspace_id,
+                         intendedWorkspaceRole: intended_workspace_role
+                       }))
+    end
+
+    # GET /users (ADMIN)
+    def list(limit: nil, offset: nil, before_date: nil, query: nil)
+      response = http_get("users", { limit: limit, offset: offset, beforeDate: before_date, query: query })
+      collection(response, key: "users")
+    end
+    alias all list
+
+    # GET /users/{id} (ADMIN)
+    def get(id)
+      object(http_get("users/#{escape(id)}"))
+    end
+    alias find get
+
+    # POST /users/{id}/activate (ADMIN)
+    def activate(id)
+      acknowledged(http_post("users/#{escape(id)}/activate"))
+    end
+
+    # POST /users/{id}/deactivate (ADMIN)
+    def deactivate(id)
+      acknowledged(http_post("users/#{escape(id)}/deactivate"))
+    end
+
+    # PUT /users/{id}/role (ADMIN) — role is one of ROLES.
+    def change_role(id, role:)
+      acknowledged(http_put("users/#{escape(id)}/role", { role: role }))
+    end
+
+    # GET /users/settings (ADMIN) — instance-wide registration settings.
+    def settings
+      object(http_get("users/settings"))
+    end
+
+    # PUT /users/settings (ADMIN)
+    def update_settings(**attributes)
+      object(http_put("users/settings", attributes))
+    end
+  end
+end

data/lib/databasus_ruby/objects/workspaces.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  # Workspaces, their members and their audit trail.
+  #
+  #   workspace = client.workspaces.create(name: "production")
+  #   client.workspaces.add_member(workspace.id, email: "ops@example.com",
+  #                                role: "WORKSPACE_ADMIN")
+  #
+  # Note that the membership endpoints live under /workspaces/memberships/{id},
+  # where {id} is still the workspace id.
+  class Workspaces < Object
+    include Endpoint
+
+    MEMBER_ROLES = %w[WORKSPACE_OWNER WORKSPACE_ADMIN WORKSPACE_MEMBER WORKSPACE_VIEWER].freeze
+
+    # GET /workspaces — the workspaces the current user belongs to.
+    def list
+      collection(http_get("workspaces"), key: "workspaces")
+    end
+
+    alias all list
+
+    # POST /workspaces
+    def create(name:)
+      object(http_post("workspaces", { name: name }))
+    end
+
+    # GET /workspaces/{id}
+    def get(id)
+      object(http_get("workspaces/#{escape(id)}"))
+    end
+    alias find get
+
+    # PUT /workspaces/{id}
+    def update(id, **attributes)
+      object(http_put("workspaces/#{escape(id)}", attributes))
+    end
+
+    # DELETE /workspaces/{id}
+    def delete(id)
+      acknowledged(http_delete("workspaces/#{escape(id)}"))
+    end
+
+    # GET /workspaces/{id}/audit-logs
+    def audit_logs(id, limit: nil, offset: nil, before_date: nil)
+      response = http_get("workspaces/#{escape(id)}/audit-logs",
+                          { limit: limit, offset: offset, beforeDate: before_date })
+      collection(response, key: "auditLogs")
+    end
+
+    # GET /workspaces/memberships/{id}/members
+    def members(id)
+      collection(http_get("workspaces/memberships/#{escape(id)}/members"), key: "members")
+    end
+
+    # POST /workspaces/memberships/{id}/members — adds an existing user or
+    # invites a new one; the response `status` says which happened
+    # (ADDED or INVITED). `role` is one of MEMBER_ROLES.
+    def add_member(id, email:, role:)
+      object(http_post("workspaces/memberships/#{escape(id)}/members", { email: email, role: role }))
+    end
+
+    # DELETE /workspaces/memberships/{id}/members/{userId}
+    def remove_member(id, user_id)
+      acknowledged(http_delete("workspaces/memberships/#{escape(id)}/members/#{escape(user_id)}"))
+    end
+
+    # PUT /workspaces/memberships/{id}/members/{userId}/role
+    def change_member_role(id, user_id, role:)
+      acknowledged(http_put("workspaces/memberships/#{escape(id)}/members/#{escape(user_id)}/role",
+                            { role: role }))
+    end
+
+    # POST /workspaces/memberships/{id}/transfer-ownership
+    def transfer_ownership(id, new_owner_email:)
+      acknowledged(http_post("workspaces/memberships/#{escape(id)}/transfer-ownership",
+                             { newOwnerEmail: new_owner_email }))
+    end
+  end
+end

data/lib/databasus_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DatabasusRuby
+  VERSION = "0.0.1"
+end