Ruby SDK

Use volcano-sdk for authentication, database queries, storage, functions, logs, locks, and realtime events. REST calls are synchronous and raise typed exceptions on failure. Ruby 3.2 or later is required; CI tests Ruby 3.2 and 3.4.

Install the published gem

Add the RubyGems package to your application:

bundle add volcano-sdk

For a new directory without a Gemfile, run bundle init first. Require the package with require "volcano".

Sign in and read a profile

Create a project, enable email and password authentication, and create a user with a confirmed email when your project requires confirmation. Use that project's anonymous key. Set VOLCANO_ANON_KEY, VOLCANO_USER_EMAIL, and VOLCANO_USER_PASSWORD in your environment. Set VOLCANO_API_URL only when using a different API endpoint, such as local mode.

Save this as quickstart.rb:

require "volcano"

client = Volcano::Client.new(
  anon_key: ENV.fetch("VOLCANO_ANON_KEY"),
  api_url: ENV.fetch("VOLCANO_API_URL", "https://api.volcano.dev")
)
session = client.auth.sign_in(
  email: ENV.fetch("VOLCANO_USER_EMAIL"),
  password: ENV.fetch("VOLCANO_USER_PASSWORD")
)
begin
  user = client.auth.user
  raise "Unexpected user" unless user.id == session.user_id

  puts "Signed in as #{user.email}"
ensure
  client.auth.sign_out
end

Run it with bundle exec ruby quickstart.rb. It signs in, fetches the server-validated profile, prints the user's email, revokes its server session, and clears the local session. An invalid email or password raises Volcano::Error::AuthenticationError; failed network requests raise Volcano::Error::TransportError. Both inherit from Volcano::Error::VolcanoError.

Keep authentication scoped to one user

A client holds its current session in memory. Use a separate client for each independent user session; do not share one mutable client across users in a web server. client.current_session and client.auth.current_session read the local immutable snapshot without a request. Use client.auth.user when you need a server-validated profile; get_user is an alias. Successful profile operations update the cached user while preserving the current credentials. Authenticated profile, session-list/deletion, email-change request/cancellation, linked-provider, provider-token, and provider-API operations refresh a usable session once after HTTP 401 and replay the original request values. Deleting the current server session also clears its refreshed local credentials; a separately adopted session remains current. These operations do not retry other HTTP failures or ambiguous network failures, and they never retry under a replacement session.

sign_up returns an acknowledgement without signing in by default. Pass sign_in_when_allowed: true to sign in only when the project does not require email confirmation. To adopt an existing session, assign a Volcano::Session containing its access token, refresh token, and user ID to client.auth.current_session. The SDK does not persist tokens for you.

For operations that require a service key, pass service_key to the constructor in trusted server code. Keep service keys and user credentials out of source control and client applications.

Use a supplied access token

For a server request that already carries a user's access token, create a client for that request:

require "volcano"

def load_request_user(access_token)
  client = Volcano::Client.new(
    anon_key: ENV.fetch("VOLCANO_ANON_KEY"),
    access_token: access_token
  )
  client.auth.user
end

Call this helper from your request handler with the bearer token from that request. For a Volcano function, use the access token in event.fetch("__volcano_auth") supplied for that invocation. The helper validates the token with Volcano before returning the user.

Once a user identity has been validated, a refresh response for another user is rejected and leaves the current credentials unchanged. Construction makes no request and does not persist credentials. The initial snapshot has nil refresh credentials, user ID, and cached user. A successful profile read fills in the validated identity and cached user while retaining the supplied access token. Without a refresh token, an HTTP 401 remains an authentication error, refresh_session raises Volcano::Error::AuthenticationError, and sign_out revokes the server session identified by the access token before clearing local state. Refresh must preserve the server session identified by the access JWT, even before a profile is loaded. A different session is rejected, including another session for the same user. Supplied credentials need a readable session identifier to refresh, even when you provide a user profile or load it from the server. Profile data does not prove that access and refresh tokens belong together. For supplied credentials, sign-out revokes the access-token session. On HTTP 401, it can refresh once and revoke that same session without adopting the renewed credentials locally. When the SDK received both credentials together from sign-in or a validated refresh, it uses the refresh token directly, even if access has expired. Sign-out joins an existing refresh and prevents later refresh attempts for that session. Concurrent sign-outs share one result; a separate sign-in or adoption remains current. Pass refresh_token alongside access_token when the client should refresh that session. A revocation failure is reported after local clearing; it does not prove that copied tokens are invalid. Assigning auth.current_session still requires complete credentials and identity.

Use the rest of the API

The SDK repository contains examples for every public facade, including database filters and mutations, resumable uploads, function invocation, log queries, lock guards, and realtime presence and database changes. Follow the realtime examples to connect and disconnect channels within their supported async task lifecycle.

See release notes for version changes and GitHub issues to report a problem. Include the gem version, Ruby version, and a minimal reproduction without credentials.

See Distributed locks for acquisition recovery, renewal, and fencing.

Read the database guide for projection, filters, ordered pagination, and mutations.

For uploads, visibility, and resumable sessions, see Storage.

See Logs for project-token authentication, search, pagination, and activity.

See Realtime for broadcasts, presence, database changes, and shutdown.

See Authentication for account, session, email, and OAuth workflows.

See Functions for standard invocation, durable execution clients, and error handling.

See Versions and compatibility for runtime support, upgrades, and restoring a tested dependency set.