envlet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d95d6b63c04a40b1c02fbd3982eeda60431a707577a7d76c736afc64ef4135d
+  data.tar.gz: 1094f02bf8515fd5887c3f4d8c767a7c80afc77bf338b1622098a228dcf1d615
+SHA512:
+  metadata.gz: aeed2b588d60817631047dac3c4299018fcca8eca07b4970daa6c8b68aa835b1202c3603193cd7587083774db9b2b3a272a2e6b292b5a200a39cd7a5dde37084
+  data.tar.gz: 7f3415e50ec21f23430a6ade7809af34df29b7d09bd4531dce38d32b4bba5ca829f4b1d2b7c2e08284a5dfd18b273174f46c2204755f72fd30286bd500493be6

data/README.md

@@ -0,0 +1,28 @@
+# envlet
+
+Pull your Envlet environment at runtime. The host platform holds one secret,
+an Envlet token, and your app loads everything else at boot.
+
+```ruby
+require "envlet"
+
+Envlet.inject
+```
+
+`Envlet.inject` fetches every value the token's identity may read and sets
+`ENV`. Values already set by the host are never overwritten. Pass
+`override: true` to force Envlet's values.
+
+```ruby
+values = Envlet.load
+stripe_key = Envlet.get("STRIPE_KEY")
+```
+
+`Envlet.load` returns a hash of names and values. `Envlet.get(name)` fetches
+one value and raises `Envlet::NotFoundError` when the identity cannot read it.
+
+Configuration comes from `ENVLET_TOKEN` or the `token:` option. Set
+`ENVLET_API_URL` or pass `api_url:` to use another API endpoint. Requests retry
+briefly on network errors and 5xx responses unless `retry: false` is set.
+Authentication failures raise `Envlet::AuthError`; every Envlet error exposes
+`code` and `status`. The SDK never returns stale or partial values.

data/lib/envlet/version.rb

@@ -0,0 +1,3 @@
+module Envlet
+  VERSION = "0.1.0"
+end

data/lib/envlet.rb

@@ -0,0 +1,202 @@
+require "json"
+require "net/http"
+require "openssl"
+require "socket"
+require "timeout"
+require "uri"
+require_relative "envlet/version"
+
+module Envlet
+  DEFAULT_API_URL = "https://api.envlet.dev"
+  RETRY_ATTEMPTS = 3
+  RETRY_DELAYS = [0.4, 1.6].freeze
+  OPEN_TIMEOUT = 2
+  READ_TIMEOUT = 2
+
+  class Error < StandardError
+    attr_reader :code, :status
+
+    def initialize(code, message, status = nil)
+      super(message)
+      @code = code
+      @status = status
+    end
+  end
+
+  class AuthError < Error
+  end
+
+  class NotFoundError < Error
+  end
+
+  class << self
+    def load(**options)
+      validate_options(options, :token, :api_url, :retry)
+      body = request(
+        "/v1/values",
+        token: options[:token],
+        api_url: options[:api_url],
+        retry_enabled: options.fetch(:retry, true)
+      )
+      values = body["values"] if body.is_a?(Hash)
+      unless values.is_a?(Hash) && values.all? { |name, value| name.is_a?(String) && value.is_a?(String) }
+        raise Error.new("invalid_response", "the values response was not in the expected shape")
+      end
+
+      values
+    end
+
+    def get(name, **options)
+      validate_options(options, :token, :api_url, :retry)
+      encoded_name = URI.encode_www_form_component(name.to_s).gsub("+", "%20")
+      body = request(
+        "/v1/values/#{encoded_name}",
+        token: options[:token],
+        api_url: options[:api_url],
+        retry_enabled: options.fetch(:retry, true)
+      )
+      value = body["value"] if body.is_a?(Hash)
+      unless value.is_a?(String)
+        raise Error.new("invalid_response", "the value response was not in the expected shape")
+      end
+
+      value
+    end
+
+    def inject(**options)
+      validate_options(options, :token, :api_url, :retry, :override)
+      values = load(
+        token: options[:token],
+        api_url: options[:api_url],
+        retry: options.fetch(:retry, true)
+      )
+      override = options.fetch(:override, false)
+      values.each do |name, value|
+        next if !override && ENV.key?(name)
+
+        ENV[name] = value
+      end
+      values
+    end
+
+    private
+
+    def validate_options(options, *allowed)
+      unknown = options.keys - allowed
+      return if unknown.empty?
+
+      raise ArgumentError, "unknown keyword: #{unknown.first}"
+    end
+
+    def request(path, token:, api_url:, retry_enabled:)
+      resolved_token = resolve_token(token)
+      base_url = resolve_api_url(api_url)
+      uri = build_uri(base_url, path)
+      attempts = retry_enabled == false ? 1 : RETRY_ATTEMPTS
+      last_error = nil
+
+      attempts.times do |attempt|
+        sleep(RETRY_DELAYS.fetch(attempt - 1, RETRY_DELAYS.last)) if attempt > 0
+
+        begin
+          response = perform_http_request(uri, resolved_token)
+        rescue Timeout::Error, EOFError, IOError, SocketError, SystemCallError,
+               OpenSSL::SSL::SSLError, Net::ProtocolError => error
+          last_error = Error.new(
+            "network_error",
+            "could not reach #{base_url}: #{error.message}"
+          )
+          next
+        end
+
+        return parse_success_response(response) if response.is_a?(Net::HTTPOK)
+
+        code, message = parse_error_response(response)
+        status = response.code.to_i
+
+        raise AuthError.new(code, message, status) if status == 401 || status == 403
+        raise NotFoundError.new(code, message, status) if status == 404
+
+        if status >= 500
+          last_error = Error.new(code, message, status)
+          next
+        end
+
+        raise Error.new(code, message, status)
+      end
+
+      raise(last_error || Error.new("request_failed", "request failed"))
+    end
+
+    def resolve_token(token)
+      token = ENV["ENVLET_TOKEN"] if token.nil?
+      unless token.nil? || token.is_a?(String)
+        raise Error.new("config_invalid", "the token must be a string")
+      end
+      if token.nil? || token.empty?
+        raise Error.new(
+          "config_missing",
+          "no token: pass token: or set ENVLET_TOKEN"
+        )
+      end
+
+      token
+    end
+
+    def resolve_api_url(api_url)
+      api_url = ENV["ENVLET_API_URL"] if api_url.nil?
+      api_url.nil? ? DEFAULT_API_URL : api_url
+    end
+
+    def build_uri(api_url, path)
+      unless api_url.is_a?(String) && !api_url.empty?
+        raise Error.new("config_invalid", "the API URL must be a non-empty string")
+      end
+
+      uri = URI.parse("#{api_url.sub(%r{/$}, "")}#{path}")
+      unless uri.is_a?(URI::HTTP) && uri.host
+        raise Error.new("config_invalid", "the API URL must use HTTP or HTTPS")
+      end
+
+      uri
+    rescue URI::InvalidURIError => error
+      raise Error.new("config_invalid", "the API URL is invalid: #{error.message}")
+    end
+
+    def perform_http_request(uri, token)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      request = Net::HTTP::Get.new(uri.request_uri)
+      request["Authorization"] = "Bearer #{token}"
+      http.start { |connection| connection.request(request) }
+    end
+
+    def parse_success_response(response)
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise Error.new("invalid_response", "the response was not valid JSON", response.code.to_i)
+    end
+
+    def parse_error_response(response)
+      code = "request_failed"
+      message = "request failed with status #{response.code}"
+
+      begin
+        body = JSON.parse(response.body)
+        envelope = body["error"] if body.is_a?(Hash)
+        if envelope.is_a?(Hash)
+          code = envelope["code"] if envelope["code"].is_a?(String)
+          message = envelope["message"] if envelope["message"].is_a?(String)
+        end
+      rescue JSON::ParserError
+      end
+
+      [code, message]
+    end
+  end
+
+  private_constant :DEFAULT_API_URL, :RETRY_ATTEMPTS, :RETRY_DELAYS,
+                   :OPEN_TIMEOUT, :READ_TIMEOUT
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: envlet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SELCOR
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-02 00:00:00.000000000 Z
+dependencies: []
+description: Load, get, or inject Envlet environment values with one token.
+email:
+- admin@selcor.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/envlet.rb
+- lib/envlet/version.rb
+homepage: https://envlet.dev
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://docs.envlet.dev
+  homepage_uri: https://envlet.dev
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Load Envlet environment values at runtime
+test_files: []