databasus_ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9223ce08d06f8a4f29e700d9046bab99ee5aaec01131af37a12620cdec27b7ed
+  data.tar.gz: 1cd2c4226183d6106dd8a351e61533c2bdf513f818bb0e43f4c3dd077fe548b0
+SHA512:
+  metadata.gz: f4c7dda68f74e63dc5833e41b2aff40c730f5462920bc8aaee57549a0b435516d187d07bd6e62591d7ef10b03f863d2492d5754da422021089bcaa4226d26fe2
+  data.tar.gz: 5c59d0c7e223f8904a54de677f5083c9cd94466e16e60d082b02ef42124784e52f28c09922fbe33542bf5e7b5f5c07c3b2e7a21a5d675e96e46cda29715ba7e7

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+## [Unreleased]
+
+### Added
+
+- `DatabasusRuby::Client` with bearer authentication, an optional default
+  `workspace_id`, an optional `agent_id`, and one memoized endpoint object per
+  API domain.
+- Endpoint coverage for `auth`, `users` (profile, administration, instance
+  settings), `workspaces` (settings, membership, audit logs), `databases`,
+  logical `backups`, `storages` and `notifiers`.
+- `DatabasusRuby::Collection`, a uniform `Enumerable` return value for every
+  list endpoint, normalizing the API's bare-array, paginated-envelope and
+  unpaginated-envelope shapes and exposing `total` / `limit` / `offset` /
+  `next_offset`.
+- `DatabasusRuby::Object` payload wrapper: nested hashes and arrays are wrapped
+  on access, snake_case reads camelCase keys, and omitted fields read as `nil`.
+- Error hierarchy under `DatabasusRuby::Error`: `APIError` and its per-status
+  subclasses carry the status and decoded body; `ConfigurationError` is raised
+  before a request when the client is missing a required value.
+- `Databases#backups` and `Databases#backup`, listing and queueing the backups
+  of one database by delegating to the `backups` endpoint.
+- RBS signatures for the full public API.
+
+## [0.0.1] - 2026-08-04
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"databasus_ruby" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["samuelfelipecorrea@gmail.com"](mailto:"samuelfelipecorrea@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 SamuelFCorrea
+
+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,305 @@
+# DatabasusRuby
+
+A Ruby client for the [Databasus](https://github.com/SamuelFCorrea/databasus_ruby) backup-management API.
+
+Each API domain is an endpoint object hanging off the client, list endpoints all
+return a `Collection`, and every response is a duck-typed `Object` you can read
+with plain method calls.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add databasus_ruby
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install databasus_ruby
+```
+
+## Usage
+
+### Authentication
+
+Databasus authenticates with a bearer token. For everything except the
+verification-agent endpoints that token is a user JWT, which you get by signing
+in:
+
+```ruby
+client = DatabasusRuby::Client.new(url: "https://databasus.example.com/api/v1/")
+
+client.auth.signin(email: "you@example.com", password: ENV["DATABASUS_PASSWORD"])
+client.users.me.email  # => "you@example.com"
+```
+
+`signin` installs the returned token on the client. If you already have a
+token, pass it as `api_key` instead:
+
+```ruby
+client = DatabasusRuby::Client.new(
+  api_key: ENV["DATABASUS_API_KEY"],
+  url: ENV.fetch("DATABASUS_URL"),
+  workspace_id: ENV["DATABASUS_WORKSPACE_ID"] # optional default, see below
+)
+```
+
+`#signup` registers and installs the token the same way; both raise
+`DatabasusRuby::Error` if the response carries no token, and the result still
+exposes it as `result.token` if you want to keep it. OAuth code exchange lives
+at `client.auth.github_callback` and `client.auth.google_callback`.
+
+### Workspaces
+
+Almost everything in Databasus is scoped to a workspace.
+
+```ruby
+client.workspaces.list.each { |workspace| puts workspace.name }
+
+workspace = client.workspaces.create(name: "production")
+client.workspaces.add_member(workspace.id, email: "ops@example.com", role: "WORKSPACE_ADMIN")
+client.workspaces.members(workspace.id).map(&:email)
+client.workspaces.audit_logs(workspace.id, limit: 50)
+```
+
+Because the workspace-scoped list endpoints all require a workspace id, you can
+set one default on the client and omit it per call:
+
+```ruby
+client.workspace_id = workspace.id
+client.databases.list   # no argument needed
+client.storages.list
+client.notifiers.list
+```
+### Databases
+
+```ruby
+databases = client.databases.list(workspace_id: workspace.id)
+databases.total
+databases.first.name
+
+database = client.databases.create(
+  name: "primary",
+  type: "POSTGRES_LOGICAL",           # DatabasusRuby::Databases::TYPES
+  workspaceId: workspace.id,
+  postgresqlLogical: {
+    host: "10.0.0.1",
+    port: 5432,
+    username: "backup",
+    password: ENV["PG_PASSWORD"],
+    database: "app_production",
+    version: "17",
+    sslMode: "require"
+  }
+)
+
+database.name
+database.postgresqlLogical.host
+database.workspace_id                 # snake_case reads camelCase keys too
+
+client.databases.test_connection(database.id)      # => true, or raises
+client.databases.update(id: database.id, name: "primary-eu")
+client.databases.copy(database.id)
+client.databases.delete(database.id)
+```
+
+A database can reach its own backups, which delegates to the `backups` endpoint
+with the same filters as `client.backups.list`:
+
+```ruby
+client.databases.backups(database.id, status: "COMPLETED", limit: 25)
+client.databases.backup(database.id)               # queue a run
+```
+
+`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
+yet.
+
+### Backups
+
+```ruby
+backups = client.backups.list(
+  database_id: database.id,
+  status: %w[COMPLETED FAILED],       # DatabasusRuby::Backups::STATUSES
+  limit: 25
+)
+
+backups.total        # => 137
+backups.next_offset  # => 25
+backups.first.fileName
+
+client.backups.create(database_id: database.id)   # queue a run
+client.backups.cancel(backup.id)
+client.backups.delete(backup.id)
+
+filename, contents = client.backups.download(backup.id)
+File.binwrite(filename, contents)
+```
+
+`#download` mints a short-lived token and streams the file in one step; use
+`#download_token` and `#file` if you need the two halves separately.
+
+### Storages and notifiers
+
+Both use a single save endpoint for create and update — include `id` in the
+payload to update.
+
+```ruby
+storage = client.storages.save(
+  name: "offsite",
+  type: "S3",                          # DatabasusRuby::Storages::TYPES
+  workspaceId: workspace.id,
+  s3Storage: { bucket: "backups", region: "eu-west-1", accessKeyId: "...", secretAccessKey: "..." }
+)
+client.storages.test(storage.id)
+client.storages.transfer(storage.id, target_workspace_id: other.id)
+
+notifier = client.notifiers.save(
+  name: "ops",
+  notifierType: "SLACK",               # DatabasusRuby::Notifiers::TYPES
+  workspaceId: workspace.id,
+  slackNotifier: { token: "...", channelId: "C123" }
+)
+client.notifiers.test(notifier.id)
+```
+
+`direct_test` on either domain tests an unsaved payload.
+
+### Users
+
+`client.users` covers both the signed-in user and instance-wide administration
+(the latter needs an `ADMIN` token):
+
+```ruby
+client.users.me.name
+client.users.update_me(name: "New Name")
+client.users.change_password(new_password: ENV["NEW_PASSWORD"])
+client.users.invite(email: "new@example.com", intended_workspace_id: workspace.id,
+                   intended_workspace_role: "WORKSPACE_MEMBER")
+
+client.users.list(query: "ops", limit: 25)   # ADMIN
+client.users.deactivate(user_id)             # ADMIN
+client.users.change_role(user_id, role: "ADMIN")
+client.users.settings                        # instance registration settings
+```
+
+### Collections
+
+Every list endpoint returns a `DatabasusRuby::Collection`, regardless of which
+of the API's three list shapes the endpoint uses:
+
+```ruby
+backups = client.backups.list(database_id: database.id, limit: 25)
+
+backups.each { |backup| ... }        # Enumerable
+backups.map(&:status)
+backups.size                         # items on this page
+backups.total                        # items overall
+backups.limit                        # nil when the endpoint does not paginate
+backups.offset
+backups.paginated?
+backups.next_offset                  # nil on the last page
+backups.last_page?
+backups.data                         # the underlying Array
+```
+
+Paging through everything:
+
+```ruby
+offset = 0
+loop do
+  page = client.backups.list(database_id: database.id, limit: 100, offset: offset)
+  page.each { |backup| process(backup) }
+  break if page.last_page?
+
+  offset = page.next_offset
+end
+```
+
+### Response objects
+
+Responses are wrapped in `DatabasusRuby::Object`, which reads keys as methods,
+wraps nested hashes and arrays as it goes, and accepts snake_case for the API's
+camelCase keys:
+
+```ruby
+database.postgresqlLogical.sslMode
+database.postgresql_logical.ssl_mode   # the same thing
+database.notifiers.map(&:name)         # arrays of objects are wrapped too
+database.to_h                          # the raw decoded payload
+database["name"]
+database.key?(:workspace_id)
+```
+
+Databasus omits empty fields, so reading a key that isn't in the payload
+returns `nil` rather than raising.
+
+### Errors
+
+Non-2xx responses raise a subclass of `DatabasusRuby::APIError` carrying the
+status and decoded body:
+
+| Status | Error |
+| --- | --- |
+| 400 | `DatabasusRuby::BadRequestError` |
+| 401 | `DatabasusRuby::AuthenticationError` |
+| 403 | `DatabasusRuby::ForbiddenError` |
+| 404 | `DatabasusRuby::NotFoundError` |
+| 409 | `DatabasusRuby::ConflictError` |
+| 429 | `DatabasusRuby::RateLimitError` |
+| 5xx | `DatabasusRuby::ServerError` |
+
+```ruby
+begin
+  client.databases.test_connection(database.id)
+rescue DatabasusRuby::BadRequestError => e
+  e.message   # => "dial tcp 10.0.0.1:5432: connect: connection refused"
+  e.status    # => 400
+  e.body      # => { "error" => "dial tcp ..." }
+end
+```
+
+`DatabasusRuby::ConfigurationError` (a sibling of `APIError` under
+`DatabasusRuby::Error`) is raised before any request goes out when the client is
+missing something it needs, such as a workspace id.
+
+## API coverage
+
+Implemented: `auth`, `users` (including user management and instance settings),
+`workspaces` (including membership and audit logs), `databases`, `backups`
+(logical), `storages`, `notifiers`.
+
+Not yet wrapped: physical backups and their configs, logical backup configs,
+restores, verifications and verification agents/configs, healthchecks, disk
+usage, global audit logs and the `system/*` endpoints. The client is ready for
+them — each is a new class in `lib/databasus_ruby/objects/` plus an accessor on
+`Client`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests, or `rake` to run the tests and RuboCop. You can
+also run `bin/console` for an interactive prompt with a preconfigured `client`.
+
+The specs stub HTTP with WebMock, so they need no running Databasus instance.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/SamuelFCorrea/databasus_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/SamuelFCorrea/databasus_ruby/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DatabasusRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/SamuelFCorrea/databasus_ruby/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/databasus_ruby/client.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+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.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`).
+  class Client
+    attr_reader :adapter, :url
+    attr_accessor :api_key, :workspace_id
+
+    def initialize(api_key: nil, url: nil, workspace_id: nil, adapter: Faraday.default_adapter)
+      raise ConfigurationError, "url is required" if url.nil? || url.to_s.empty?
+
+      @api_key = api_key
+      @adapter = adapter
+      @url = normalize_url(url)
+      @workspace_id = workspace_id
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.url_prefix = url
+        conn.request :json
+        conn.response :json, content_type: "application/json"
+        conn.adapter adapter
+      end
+    end
+
+    def auth
+      @auth ||= Auth.new(self)
+    end
+
+    def backups
+      @backups ||= Backups.new(self)
+    end
+
+    def databases
+      @databases ||= Databases.new(self)
+    end
+
+    def notifiers
+      @notifiers ||= Notifiers.new(self)
+    end
+
+    def storages
+      @storages ||= Storages.new(self)
+    end
+
+    def users
+      @users ||= Users.new(self)
+    end
+
+    def workspaces
+      @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.
+    def workspace_id!
+      return workspace_id unless workspace_id.nil? || workspace_id.to_s.empty?
+
+      raise ConfigurationError,
+            "workspace_id is required: pass workspace_id: to this call or to Client.new"
+    end
+
+    # Performs the request and raises the matching APIError subclass on a
+    # non-successful status. Returns the raw Faraday::Response so callers can
+    # 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
+        req.body = body unless body.nil?
+        req.headers.update(request_headers(headers))
+      end
+
+      raise APIError.from_response(response) unless response.success?
+
+      response
+    end
+
+    def inspect
+      "#<#{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 request_headers(extra)
+      headers = {}
+      headers["Authorization"] = "Bearer #{api_key}" unless api_key.nil? || api_key.to_s.empty?
+      headers.update(extra) if extra
+      headers
+    end
+
+    # Faraday resolves a path without a leading slash against url_prefix, so
+    # the prefix has to keep its trailing slash or /api/v1 would be dropped.
+    def normalize_url(url)
+      url.to_s.end_with?("/") ? url.to_s : "#{url}/"
+    end
+
+    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
+      end
+    end
+  end
+end

data/lib/databasus_ruby/collection.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+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.
+  class Collection
+    include Enumerable
+
+    attr_reader :data, :total, :limit, :offset
+
+    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
+    end
+
+    # `key` names the array inside an envelope response and is ignored for
+    # bare-array responses.
+    def self.from(body, key:)
+      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}"
+      end
+    end
+
+    def each(&block)
+      return data.each unless block
+
+      data.each(&block)
+      self
+    end
+
+    def size
+      data.size
+    end
+    alias length size
+
+    def empty?
+      data.empty?
+    end
+
+    def [](index)
+      data[index]
+    end
+
+    def last
+      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?
+    end
+
+    def inspect
+      "#<#{self.class.name} size=#{size} total=#{total} limit=#{limit.inspect} offset=#{offset.inspect}>"
+    end
+  end
+end

data/lib/databasus_ruby/endpoint.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module DatabasusRuby
+  # Shared plumbing for the per-domain endpoint classes. Each domain is a
+  # single class (DatabasusRuby::Databases, DatabasusRuby::Backups, ...) that
+  # inherits Object and includes this module, so it carries both the endpoint
+  # methods and the payload-reading behaviour.
+  #
+  # The transport helpers are prefixed `http_` so domain classes are free to
+  # expose the natural #get / #create / #update / #delete names.
+  module Endpoint
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+      # Endpoint objects are callers, not payloads; leaving @attributes nil
+      # makes Object#method_missing raise NoMethodError on a typo instead of
+      # quietly answering nil.
+      @attributes = nil
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def http_get(path, params = nil)
+      client.request(:get, path, params: params)
+    end
+
+    def http_post(path, body = nil, params: nil)
+      client.request(:post, path, body: compact(body), params: params)
+    end
+
+    def http_put(path, body = nil, params: nil)
+      client.request(:put, path, body: compact(body), params: params)
+    end
+
+    def http_delete(path, params = nil)
+      client.request(:delete, path, params: params)
+    end
+
+    # Wraps a single-object response.
+    def object(response)
+      Object.new(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)
+    end
+
+    # For endpoints that answer 200/204 with no meaningful body.
+    def acknowledged(_response)
+      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)
+      return body unless body.is_a?(Hash)
+
+      body.each_with_object({}) do |(key, value), acc|
+        acc[key.to_s] = value unless value.nil?
+      end
+    end
+
+    # Fills in the client's default workspace for create/save payloads that
+    # did not name one explicitly.
+    def with_default_workspace(attributes)
+      return attributes if attributes.key?(:workspaceId) || attributes.key?("workspaceId")
+      return attributes if client.workspace_id.nil?
+
+      attributes.merge(workspaceId: client.workspace_id)
+    end
+
+    def escape(segment)
+      URI.encode_uri_component(require_id(segment))
+    end
+
+    # Same presence check as #escape for ids that travel in a query string or
+    # body, where Faraday does the encoding.
+    def require_id(segment)
+      raise ArgumentError, "id is required" if segment.nil? || segment.to_s.empty?
+
+      segment.to_s
+    end
+  end
+end