envless-sdk 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b6f191fde8f917a2a05741ffc41fdb3f0f5555c6cd40f77ef62eee17f4ebe79
+  data.tar.gz: 9a9b3a4001d28af65d39ea62e59339d5965c82775d7674ce3478ab737328d8f4
+SHA512:
+  metadata.gz: ee19e6d5b3d1c39afb10f480c61b1f0402c785f645fbb9f07831968ba23804d79a4c8957471fe8a81d2f3e189451a66bbd7353f63687ba1c0e1bf25c9d2b82db
+  data.tar.gz: 30dfed76e0191bcf6fb253252bfbf75082d2637dd1716da8d7c81ba5197c4bfe1aaec09b8c8b147a718cab4b492a4a9a2917eea363708f013c152611df80a847

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.0.1
+
+The first release of the Ruby gem. It covers the whole TypeScript SDK as it stands in this repository: 113 methods across 13 namespaces, each under its TypeScript name in snake_case. `rake parity` proves that every one of them sends exactly the request its TypeScript twin sends, with no options, with every option set and with the body passed as keywords, and retries, fails and returns the same way. It also proves the encryption, the validators, webhook verification and passphrase rotation agree with TypeScript on the same inputs, and that ciphertext written by either one is read by the other.
+
+### Added
+
+`Envless::Client` has a reader for every namespace, from `variables` and `versions` to `workspace.domain` and `products.access`. `listAll` is `list_all`, `getById` is `get_by_id` and `reencryptEntries` is `reencrypt_entries`. A request body goes in as keyword arguments or as one Hash, its keys keep the API's camelCase names, the options of a call are snake_case keywords (`product:`, `limit:`, `offset:`, `search:`, `order:`, `status:`, `reattempt:`), and a response comes back as a Hash with Symbol keys.
+
+    client = Envless::Client.new(token: ENV.fetch("ENVLESS_TOKEN"))
+    client.variables.create("api", "production", name: "API_KEY", value: ciphertext)
+
+Every paginated resource has `list`, which returns one `Envless::Page` with `items` and `pagination`, `list_all`, which returns every item as an Array, and `iterate`, which yields each item to a block or returns an Enumerator that fetches the next page only when it gets there.
+
+An API refusal raises `Envless::ApiError`, which carries `status`, `code`, `resource`, `field`, `request_id` and `retry_after_seconds`, and answers `auth?`, `scope_missing?`, `validation?`, `not_found?`, `conflict?`, `rate_limited?` and `needs_upgrade?`. No response at all raises `Envless::NetworkError`, with `timeout?` when the deadline passed. A value that cannot be decrypted raises `Envless::DecryptionError`, a delivery that fails verification raises `Envless::WebhookVerificationError`, and all of them inherit `Envless::Error`.
+
+`encrypt_value`, `decrypt_value`, `encrypt_with_key`, `decrypt_with_key`, `derive_workspace_key`, `import_workspace_key`, `ciphertext?`, `passphrase_strength` and `ENCRYPTION_PARAMETERS` produce and read the same `v1:` and `v2:` envelopes as the TypeScript and Python SDKs, the CLI and the dashboard: AES-256-GCM under a PBKDF2-SHA-256 key with 200,000 iterations and the workspace salt. `rotate_workspace_passphrase` re-encrypts an environment and its version history under a new passphrase, and lists in `failures` any version entry whose encrypted default it cannot rewrite because the entry's own value is not ciphertext. `variable_name_validation` and `verify_webhook_signature` behave as their TypeScript twins. Plaintext, passphrases and workspace ids must be valid UTF-8, and a raw key goes in only as 32 binary bytes, so binary data or a passphrase passed by mistake raises `ArgumentError` instead of producing ciphertext nothing else can read.
+
+`Envless.variables` and every other namespace reach a shared client, built from `ENVLESS_TOKEN` and `ENVLESS_API_ENDPOINT` the first time one is touched, and `Envless.init(...)` configures it once at startup. `client.raw.request` reaches an endpoint no method wraps yet, with the client's key, base URL, timeout and retries.
+
+`GET`, `PUT` and `DELETE` requests are retried on 408, 429, 500, 502, 503 and 504, with exponential backoff or the wait `Retry-After` asks for, capped at 30 seconds. `timeout` bounds each attempt, redirects and the response body included. Every request carries `User-Agent: envless-sdk-ruby/0.0.1`.
+
+The gem ships RBS signatures for every method, body and response, with a manifest that declares the standard libraries they use, so `library "envless-sdk"` in a Steepfile is all a project needs. It needs Ruby 3.2 or newer and has no runtime dependencies.

data/README.md

@@ -0,0 +1,171 @@
+<div align='center'>
+   <a href='https://envless.cloud'>
+        <img
+            src='https://cdn-prod.envless.cloud/assets/npm/logo.svg'
+            alt='Envless Logo'
+            width='180'
+        />
+   </a>
+
+   <br />
+</div>
+
+<p align='center'>
+    End-to-end encrypted environment variables for teams. Manage workspaces, projects, environments and secrets from code.
+</p>
+
+<p align='center'>
+    <a href='https://envless.cloud'>
+        <b>
+            Website
+        </b>
+    </a>
+    •
+    <a href='https://envless.cloud/dashboard'>
+        <b>
+            Dashboard
+        </b>
+    </a>
+    •
+    <a href='https://envless.cloud/docs/ruby/overview'>
+        <b>
+            Documentation
+        </b>
+    </a>
+    •
+    <a href='https://status.envless.cloud'>
+        <b>
+            Services Status
+        </b>
+    </a>
+</p>
+
+<br />
+
+## Intro to the Ruby Gem
+
+The official Ruby client for the Envless API. It has every method of the TypeScript SDK, all 113 across 13 namespaces, under the same names in snake_case, and ships RBS signatures for all of them. It runs on Ruby 3.2 and newer and has no runtime dependencies: HTTP is `Net::HTTP` and the encryption is `OpenSSL`, both from the standard library, with a pool of kept-alive connections that one client shares safely across threads and rebuilds after a fork.
+
+It carries an API key with write access, so it belongs on a server, in a job or in CI.
+
+### Installing
+```bash
+bundle add envless-sdk
+```
+
+Or `gem install envless-sdk` without Bundler. You require it as `envless/sdk` and use it as `Envless`. The `envless` gem on RubyGems is an unrelated project, so `gem install envless` installs something else.
+
+### Using
+```ruby
+require "envless/sdk"
+
+passphrase = ENV.fetch("ENVLESS_PASSPHRASE")
+workspace_id = Envless.me.get[:workspaceId]
+
+Envless.variables.create("api", "production",
+  name: "STRIPE_SECRET_KEY",
+  value: Envless.encrypt_value("sk_live_51H...", passphrase, workspace_id))
+```
+
+`Envless.variables`, `Envless.me` and every other namespace use a shared client that reads `ENVLESS_TOKEN` the first time one is touched. Call `Envless.init(...)` once at startup to configure it, or build your own with `Envless::Client.new`, which reads the same variable when you pass no token.
+
+Values are encrypted on your machine, never by the server, so a plaintext value is refused. A request body goes in as keyword arguments or as one Hash, and its keys keep the API's own names, so `defaultValue:` and `projectIds:` read exactly as they do in the API reference. The options of a call are snake_case keywords: `product:`, `limit:`, `offset:`, `search:`, `order:`, `status:`, `reattempt:` and `timeout:`. A response comes back as the parsed JSON, a Hash with Symbol keys, read with `variable[:updatedAt]`.
+
+The gem ships RBS signatures in `sig/`, with a record type for every body and response, so Steep and editors that read RBS check the keys and the types of each call. `library "envless-sdk"` in your Steepfile loads them, along with the standard libraries they use.
+
+### A client of your own
+```ruby
+require "envless/sdk"
+
+client = Envless::Client.new(token: ENV.fetch("ENVLESS_TOKEN"), timeout: 10, max_retries: 2)
+
+client.variables.iterate("api", "production", product: "billing") do |variable|
+  puts "#{variable[:name]} #{variable[:updatedAt]}"
+end
+
+client.close
+```
+
+A client is frozen once built, is safe to share between threads and closes its idle connections with `close`.
+
+### Pagination
+Every collection has `list` for one page, `list_all` for every page at once as an Array, and `iterate`, which yields each item to a block, or without one returns an Enumerator that fetches the next page only when it gets there, so `first(10)` stops early. A page is an `Envless::Page` with `items` and `pagination`, plus `has_more?` and `total_count`. `products.access.list` returns an `Envless::ProductAccessPage`, which also answers `private?`.
+
+### Encryption
+```ruby
+require "envless/sdk"
+
+workspace_id = Envless.me.get[:workspaceId]
+key = Envless.derive_workspace_key(ENV.fetch("ENVLESS_PASSPHRASE"), workspace_id)
+
+secrets = Envless.variables.list_all("api", "production").filter_map do |variable|
+  value = variable[:value]
+  [variable[:name], Envless.decrypt_with_key(key, value)] if value && Envless.ciphertext?(value)
+end.to_h
+```
+
+`encrypt_value` and `decrypt_value` derive the key on every call, which costs 200,000 rounds of PBKDF2. To work with many values, derive the key once with `derive_workspace_key`, or load the `ENVLESS_KEY` your CI holds with `import_workspace_key`, then use `encrypt_with_key` and `decrypt_with_key`. An `Envless::WorkspaceKey` never prints its bytes, and `to_bytes` hands them over when you need them. The `_with_key` methods also take those 32 bytes as a binary String, but never as text, so a passphrase can't be mistaken for a key. Plaintext, passphrases and workspace ids must be valid UTF-8: binary data raises `ArgumentError` rather than being changed silently, so encode it first, for example as base64. Ciphertext from this gem and from the TypeScript and Python SDKs, the CLI and the dashboard is interchangeable.
+
+`ciphertext?`, `passphrase_strength`, `variable_name_validation` and `ENCRYPTION_PARAMETERS` work exactly as they do in TypeScript. The two validators return an `Envless::Validation` with `valid?` and `error`.
+
+### Rotating the passphrase
+```ruby
+require "envless/sdk"
+
+result = Envless.rotate_workspace_passphrase(client: Envless.client, workspace_unique_id: Envless.me.get[:workspaceId],
+  from: ENV.fetch("ENVLESS_PASSPHRASE"), to: ENV.fetch("ENVLESS_NEW_PASSPHRASE"), project: "api", environment: "production")
+
+puts result.variables, result.version_entries, result.skipped.size, result.failures.size
+```
+
+It re-encrypts an environment and its version history under the new passphrase and refuses one that `passphrase_strength` rejects. Values that are not ciphertext are left alone and listed in `skipped`, and anything that failed to decrypt or that the API refused is listed in `failures`, so a partial run can be retried. A version entry whose own value is not ciphertext lands in `failures` too when its default is, because the API cannot rewrite that default.
+
+### Errors
+```ruby
+require "envless/sdk"
+
+begin
+  Envless.variables.get("api", "production", "MISSING")
+rescue Envless::ApiError => error
+  raise unless error.not_found?
+
+  warn [error.code, error.request_id].join(" ")
+end
+```
+
+An API refusal raises `Envless::ApiError`, with `status`, `code`, `resource`, `field`, `request_id` and `retry_after_seconds`, plus `auth?`, `scope_missing?`, `validation?`, `not_found?`, `conflict?`, `rate_limited?` and `needs_upgrade?`. No response at all raises `Envless::NetworkError`, with `timeout?` when the deadline passed. A value that cannot be decrypted raises `Envless::DecryptionError`, and a delivery that fails verification raises `Envless::WebhookVerificationError`. All of them inherit `Envless::Error`. An unusable variable name is refused before anything is sent, with the same `ApiError` the API would answer with, and a mistake in the call itself, such as an empty slug, raises `ArgumentError`.
+
+### Webhooks
+```ruby
+class EnvlessWebhooksController < ActionController::API
+  def create
+    event = Envless.verify_webhook_signature(
+      payload: request.raw_post,
+      headers: request.headers,
+      secret: Rails.application.credentials.envless_webhook_secret
+    )
+
+    Rails.logger.info("#{event[:type]} #{event[:data]}")
+    head :no_content
+  rescue Envless::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+It checks the signature in constant time and rejects a delivery more than five minutes old, then returns the parsed event. Pass the raw body, since a parsed or re-encoded body no longer matches its signature. The headers can be a Hash in any case, a Rack env or Rails' `request.headers`.
+
+### Configuring
+`Envless::Client.new` takes `token:`, `base_url:`, `timeout:`, `max_retries:`, `adapter:`, `user_agent:` and `disable_update_notice:`. `base_url` also comes from `ENVLESS_API_ENDPOINT`. `timeout` is in seconds, bounds each attempt including redirects and the response body, and `0` turns it off. `GET`, `PUT` and `DELETE` requests are retried on 408, 429, 500, 502, 503 and 504, up to three times with exponential backoff, waiting what `Retry-After` asks for up to 30 seconds. Writes that cannot safely repeat are not retried. Every method also takes `timeout:` for that one call.
+
+`adapter:` swaps the HTTP layer for anything that responds to `call(request)`, receives an `Envless::HttpRequest` and returns an object with `status`, `headers` and `body`. The default honours `http_proxy`, `https_proxy` and `no_proxy`.
+
+An endpoint no method wraps yet is one `raw.request` away, with the client's key, base URL, timeout and retries applied:
+
+```ruby
+require "envless/sdk"
+
+Envless.client.raw.request("/projects", method: :post, body: {name: "Billing", slug: "billing"})
+```
+
+When a newer version is on RubyGems the client says so once on a terminal. `ENVLESS_DISABLE_UPDATE_NOTICE=1` or `disable_update_notice: true` turns that off.

data/lib/envless/sdk/api_error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Envless
+  class ApiError < Error
+    attr_reader :status, :code, :resource, :field, :request_id, :retry_after_seconds
+
+    def initialize(message = nil, status: nil, code: Constants::ERROR_CODES[:SERVER_ERROR], resource: nil, field: nil,
+      request_id: nil, retry_after_seconds: nil)
+      super(message)
+      @status = status
+      @code = code
+      @resource = resource
+      @field = field
+      @request_id = request_id
+      @retry_after_seconds = retry_after_seconds
+    end
+
+    def detailed_message(highlight: false, **options)
+      "#{super} [#{[status, code].compact.join(" ")}#{", request #{request_id}" if request_id}]"
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status.inspect} code=#{code.inspect} message=#{message.inspect}>"
+    end
+
+    def auth?
+      code.to_s.start_with?("auth.")
+    end
+
+    def scope_missing?
+      code == "auth.scope_missing"
+    end
+
+    def validation?
+      status == 400
+    end
+
+    def not_found?
+      status == 404
+    end
+
+    def conflict?
+      status == 409
+    end
+
+    def rate_limited?
+      status == 429
+    end
+
+    def needs_upgrade?
+      status == 402
+    end
+  end
+end

data/lib/envless/sdk/bodies.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Envless
+  module Bodies
+    module_function
+
+    def merge(body, fields)
+      base = hash_of(body).transform_keys(&:to_s)
+      base.merge(fields.to_h { |key, value| [key.to_s, value] })
+    end
+
+    def hash_of(body)
+      return {} if body.nil?
+
+      mapping(body) || raise(ArgumentError, Messages::BODY_SHAPE)
+    end
+
+    def mapping(value)
+      return value if value.is_a?(Hash)
+      return value.to_hash if value.respond_to?(:to_hash)
+
+      value.to_h if value.is_a?(Struct) || value.is_a?(Data)
+    end
+
+    def entries(values, name)
+      list(values, name).map do |value|
+        hash = mapping(value)
+        hash ? hash.to_h { |key, item| [key.to_s, item] } : value
+      end
+    end
+
+    def list(values, name)
+      return values if values.is_a?(Array)
+      return values.to_a if values.is_a?(Set)
+
+      raise ArgumentError, format(Messages::LIST_SHAPE, name:, kind: values.class)
+    end
+
+    def field(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash.key?(key) ? hash[key] : hash[key.to_sym]
+    end
+
+    def field?(hash, key)
+      hash.is_a?(Hash) && (hash.key?(key) || hash.key?(key.to_sym))
+    end
+  end
+end

data/lib/envless/sdk/client.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Envless
+  class Client
+    attr_reader :raw, :me, :workspace, :workspaces, :products, :projects, :environments, :variables, :versions,
+      :members, :invites, :roles, :keys, :webhooks
+
+    def initialize(token_argument = nil, token: nil, base_url: nil, adapter: nil, max_retries: nil, timeout: nil,
+      user_agent: nil, disable_update_notice: false)
+      raise ArgumentError, Messages::TOKEN_TWICE unless token_argument.nil? || token.nil?
+
+      @raw = Transport.new(token: Environment.resolve_token(token.nil? ? token_argument : token),
+        base_url: Environment.resolve_base_url(base_url), adapter:, max_retries:, timeout:, user_agent:,
+        disable_update_notice:)
+      @me = Resources::Me.new(@raw)
+      @workspace = Resources::Workspace.new(@raw)
+      @workspaces = Resources::Workspaces.new(@raw)
+      @products = Resources::Products.new(@raw)
+      @projects = Resources::Projects.new(@raw)
+      @environments = Resources::Environments.new(@raw)
+      @variables = Resources::Variables.new(@raw)
+      @versions = Resources::Versions.new(@raw)
+      @members = Resources::Members.new(@raw)
+      @invites = Resources::Invites.new(@raw)
+      @roles = Resources::Roles.new(@raw)
+      @keys = Resources::Keys.new(@raw)
+      @webhooks = Resources::Webhooks.new(@raw)
+      freeze
+    end
+
+    def close
+      @raw.close
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@raw.base_url.inspect}>"
+    end
+  end
+end

data/lib/envless/sdk/clock.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Envless
+  module Clock
+    module_function
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def deadline(seconds)
+      seconds && (now + seconds)
+    end
+
+    def remaining(deadline)
+      return nil if deadline.nil?
+
+      left = deadline - now
+      raise Timeout::Error if left <= 0
+
+      left
+    end
+  end
+end

data/lib/envless/sdk/connection_pool.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Envless
+  class ConnectionPool
+    CLOSE_ERRORS = [IOError, SystemCallError, OpenSSL::SSL::SSLError].freeze
+
+    def initialize(max_idle:, keep_alive_timeout:)
+      @max_idle = max_idle
+      @keep_alive_timeout = keep_alive_timeout
+      @idle = Hash.new { |pools, key| pools[key] = [] }
+      @lock = Mutex.new
+      @pid = Process.pid
+    end
+
+    def checkout(uri, timeout)
+      while (pooled = take(uri))
+        return [pooled, true] if usable?(pooled)
+
+        discard(pooled)
+      end
+
+      [Connector.open(uri, timeout, @keep_alive_timeout), false]
+    end
+
+    def checkin(uri, connection)
+      kept = @lock.synchronize do
+        room = @pid == Process.pid && @idle[key(uri)].size < @max_idle
+        @idle[key(uri)].push(connection) if room
+        room
+      end
+
+      discard(connection) unless kept
+    end
+
+    def discard(connection)
+      connection.finish if connection.started?
+    rescue *CLOSE_ERRORS
+      nil
+    end
+
+    def close
+      drained = @lock.synchronize do
+        connections = @idle.values.flatten
+        connections.clear unless @pid == Process.pid
+        @idle.clear
+        @pid = Process.pid
+        connections
+      end
+
+      drained.each { |connection| discard(connection) }
+      nil
+    end
+
+    private
+
+    def take(uri)
+      @lock.synchronize do
+        forget_inherited
+        @idle[key(uri)].pop
+      end
+    end
+
+    def usable?(connection)
+      io = connection.instance_variable_get(:@socket)&.io
+      return true if io.nil?
+
+      !io.closed? && !io.to_io.wait_readable(0)
+    rescue *CLOSE_ERRORS
+      false
+    end
+
+    def forget_inherited
+      return if @pid == Process.pid
+
+      @idle.clear
+      @pid = Process.pid
+    end
+
+    def key(uri)
+      [uri.scheme.to_s.downcase, uri.hostname.to_s.downcase, uri.port]
+    end
+  end
+end

data/lib/envless/sdk/connector.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Envless
+  module Connector
+    module_function
+
+    def open(uri, timeout, keep_alive_timeout)
+      proxy = uri.find_proxy
+      connection = Net::HTTP.new(uri.hostname.to_s, uri.port, proxy&.hostname, proxy&.port, decoded(proxy&.user),
+        decoded(proxy&.password))
+      connection.use_ssl = uri.scheme.to_s.casecmp?("https")
+      connection.min_version = OpenSSL::SSL::TLS1_2_VERSION if connection.use_ssl?
+      connection.open_timeout = timeout
+      connection.read_timeout = timeout
+      connection.write_timeout = timeout
+      connection.keep_alive_timeout = keep_alive_timeout
+      connection.max_retries = 0
+      connection.ignore_eof = false
+      connection.start
+    end
+
+    def decoded(text)
+      text && URI.decode_uri_component(text)
+    end
+  end
+end