strato_env 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f79b3af1cf5e9b6351c48ecc18b5bce119962fc5a936c90fe74d11b61afaaaa5
+  data.tar.gz: 74da0decc7537880ef50dd89085a17ca59c9300385010951daea8879f0cbd241
+SHA512:
+  metadata.gz: b88ad19cc8e7e566d547949b1bf814604f68d4e2c23984cde6802e70b8146989e08ef3f7bdff6dff3cd9065c404df5bea3f448ac1c87f68fb65caf7139148ddf
+  data.tar.gz: fdd5fd297ec109cb077e734a7e827da4d063c25ee9da91c24aac9571a7322d064ea9b39b8cdad6fe0c7a276a1229b0c68f613737e6b4001cec4d9e1bb787080c

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - 2026-05-15
+
+## Added
+
+- Initial release. Load one or more AWS SSM Parameter Store paths into ENV at boot, with later paths overriding earlier ones.
+- Pluggable fetcher contract: anything that responds to `#call(path)` and returns `Hash<String, String>` works as a backend. Default is `StratoEnv::SSMFetcher`.
+- `StratoEnv.fetch(paths:)` returns the merged hash without touching ENV — for previewing or applying elsewhere.
+- `StratoEnv.apply(hash)` writes a hash to ENV — for composing `fetch` with custom merge/diff logic before applying.
+
+[0.1.0]: https://github.com/samsonjs/strato_env/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sami Samhuri
+
+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,194 @@
+# strato_env
+
+A small Ruby gem that loads layered configuration into `ENV` at boot. Point it at one or more paths and it sets `ENV` vars from the values fetched. Multiple paths form layers, with later paths overriding earlier ones — so you can split common config from host-specific or environment-specific overrides.
+
+The default backend is [AWS SSM Parameter Store][ssm], but the loader is decoupled from the backend: pass any callable that takes a path and returns a `Hash<String, String>` (anything responding to `#call(path)` — `Proc`, lambda, `Method`, or a class with `#call` defined). That makes testing trivial and adding new backends (Secrets Manager, Vault, a YAML file) a few lines of glue.
+
+No Rails dependency. Works in Rails, Sinatra, Lambda, scripts, or any Ruby boot process.
+
+The name comes from the Italian word *strato*, meaning "layer" — the gem is about layering configuration.
+
+[ssm]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html
+
+---
+
+- [Quick start](#quick-start)
+- [Layered loading](#layered-loading)
+- [Preview without applying](#preview-without-applying)
+- [Custom orchestration: fetch + apply](#custom-orchestration-fetch--apply)
+- [Where to call it from](#where-to-call-it-from)
+- [Customising the SSM fetcher](#customising-the-ssm-fetcher)
+- [Custom fetchers](#custom-fetchers)
+- [Testing](#testing)
+- [License](#license)
+- [Contribution guide](#contribution-guide)
+
+## Quick start
+
+```
+$ gem install strato_env
+```
+
+```ruby
+require "strato_env"
+
+StratoEnv.load(paths: "/myapp/staging/")
+# ENV is now populated with one entry per parameter under that path.
+```
+
+A parameter named `/myapp/staging/DATABASE_URL` becomes `ENV["DATABASE_URL"]`. By default, `SecureString` parameters are decrypted automatically.
+
+`.load` returns an `Array<String>` of the ENV var names that were set.
+
+## Layered loading
+
+Pass an array to layer multiple paths. Later paths override earlier ones, so the rightmost path wins on collisions.
+
+```ruby
+rails_env    = ENV.fetch("RAILS_ENV")        # "staging"
+role         = ENV.fetch("HOST_ROLE")        # "web" or "worker"
+extra_layers = ENV.fetch("EXTRA_LAYERS", "") # "ruby4_0,blah,..."
+
+StratoEnv.load(paths: [
+  "/myapp/#{rails_env}/common/",
+  "/myapp/#{rails_env}/#{role}/",
+  *extra_layers.split(',').map { "/myapp/#{rails_env}/#{it}/" },
+])
+```
+
+This pattern lets you keep shared config (database URL, API keys) under `common/` and override only the host-specific values (queue URLs, log destinations) under `web/` or `worker/`.
+
+I also use this for validating a new deployment of an environment before promoting it, e.g. for upgrading from Ruby 3.4 to 4.0. Sometimes you have to override a couple things so I'll layer on those refinements with `/myapp/staging/ruby4_0/`.
+
+## Preview without applying
+
+`StratoEnv.fetch` returns the merged hash without touching ENV. Useful for previewing, logging, or applying to somewhere other than `ENV`.
+
+```ruby
+StratoEnv.fetch(paths: ["/myapp/common/", "/myapp/web/"])
+# => { "DATABASE_URL" => "postgres://...", "LOG_LEVEL" => "debug" }
+```
+
+## Custom orchestration: fetch + apply
+
+For more complex flows — e.g. merging from multiple namespaces, diffing them, warning on overrides — fetch each source separately, merge however you like, then `apply` the result. `StratoEnv.load(paths:)` is just sugar for `apply(fetch(paths: paths))`.
+
+```ruby
+loader = StratoEnv.new
+
+# Fetch two namespaces independently (no ENV side effects yet).
+terraform_env = loader.fetch(paths: ["/terraform/myapp/common/", "/terraform/myapp/web/"])
+human_env     = loader.fetch(paths: ["/myapp/common/",            "/myapp/web/"])
+
+# Apply your own policy. Here: humans win, but warn on divergence.
+terraform_env.each do |name, tf_value|
+  next unless human_env.key?(name) && human_env[name] != tf_value
+  warn("[env] #{name}: human value overrides terraform.")
+end
+
+loader.apply(terraform_env.merge(human_env))
+```
+
+`#apply(hash)` writes the hash to ENV and returns the array of names set, same return shape as `#load`. Also available as the class method `StratoEnv.apply(hash)`.
+
+## Where to call it from
+
+Call `StratoEnv.load` as early in boot as possible, before any code reads the ENV vars it needs to populate.
+
+### Rails
+
+For Rails apps, put the call at the top of your environment file, before `Rails.application.configure`. The configure block typically reads ENV (`ENV.fetch("REDIS_URL")`, etc.), so the fetcher has to run first.
+
+```ruby
+# config/environments/production.rb
+require "strato_env"
+
+rails_env = ENV.fetch("RAILS_ENV")
+role      = ENV.fetch("HOST_ROLE")
+
+StratoEnv.load(paths: [
+  "/myapp/#{rails_env}/common/",
+  "/myapp/#{rails_env}/#{role}/",
+])
+
+Rails.application.configure do
+  # ... now safe to read ENV ...
+end
+```
+
+`config/initializers/*.rb` runs too late — the environment file's body has already executed by then.
+
+### Lambda / scripts
+
+Just call it before reading the values:
+
+```ruby
+require "strato_env"
+
+StratoEnv.load(paths: "/myapp/prod/")
+# ... rest of your script ...
+```
+
+## Customising the SSM fetcher
+
+The default fetcher is `StratoEnv::SSMFetcher`. To pass options to it (recursive lookups, decryption off, a pre-configured client), build it yourself and pass it to `StratoEnv.new`:
+
+```ruby
+fetcher = StratoEnv::SSMFetcher.new(
+  recursive: true,         # fetch parameters nested under the path
+  with_decryption: false,  # leave SecureString values encrypted
+  client: my_ssm_client,   # custom region/credentials
+)
+
+StratoEnv.new(fetcher: fetcher).load(paths: "/myapp/staging/")
+```
+
+`StratoEnv.load` and `StratoEnv.fetch` are class-method shortcuts for `StratoEnv.new.load` / `StratoEnv.new.fetch` — i.e. the default `SSMFetcher` with all defaults.
+
+## Custom fetchers
+
+A fetcher is any callable that takes a path and returns a `Hash<String, String>`. Anything that responds to `#call(path)` works: a `Proc`, a lambda, a `Method` object, or a class with `#call` defined.
+
+```ruby
+yaml_fetcher = ->(path) { YAML.load_file(path) }
+StratoEnv.new(fetcher: yaml_fetcher).load(paths: "config/app.yml")
+```
+
+This is what makes the loader trivial to test: pass a stub fetcher in your specs and assert the right keys land in `ENV`. No AWS SDK mocking required.
+
+```ruby
+StubFetcher = Data.define(:values) do
+  def call(_path) = values
+end
+
+stub = StubFetcher.new(values: { "DATABASE_URL" => "postgres://test" })
+StratoEnv.new(fetcher: stub).load(paths: "/anything/")
+
+ENV["DATABASE_URL"] # => "postgres://test"
+```
+
+## Testing
+
+For testing the bundled `SSMFetcher`, the `aws-sdk-ssm` gem ships with stub support:
+
+```ruby
+client = Aws::SSM::Client.new(stub_responses: true, region: "us-east-1")
+client.stub_responses(:get_parameters_by_path, {
+  parameters: [
+    { name: "/myapp/test/DATABASE_URL", value: "postgres://localhost/test", type: "String" },
+  ],
+})
+
+StratoEnv::SSMFetcher.new(client: client).call("/myapp/test/")
+# => { "DATABASE_URL" => "postgres://localhost/test" }
+```
+
+For testing your *loader* logic, prefer a stub fetcher (see [Custom fetchers](#custom-fetchers)) — no AWS SDK setup needed.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Contribution guide
+
+Pull requests are welcome! Make sure that new code is reasonably well tested and all the checks pass. I'm happy to provide a bit of direction and guidance if you're unsure how to proceed with any of these things.

data/lib/strato_env/ssm_fetcher.rb

@@ -0,0 +1,40 @@
+require "aws-sdk-ssm"
+
+class StratoEnv
+  # SSM Parameter Store implementation of the fetcher protocol used by
+  # {StratoEnv}.
+  #
+  # Given a path, returns a +Hash<String, String>+ mapping each parameter's
+  # basename (last path component) to its value. Pages are followed
+  # transparently and +SecureString+ values are decrypted by default.
+  #
+  # @example
+  #   fetcher = StratoEnv::SSMFetcher.new(recursive: true)
+  #   fetcher.call("/myapp/")
+  #   # => { "DATABASE_URL" => "postgres://...", "REDIS_URL" => "redis://..." }
+  class SSMFetcher
+    # @param client [Aws::SSM::Client, nil] an SSM client. Defaults to a new
+    #   {Aws::SSM::Client} configured from the ambient AWS environment.
+    # @param recursive [Boolean] whether to fetch parameters nested beneath the
+    #   given path. Defaults to +false+ to match the common one-level layout.
+    # @param with_decryption [Boolean] decrypt +SecureString+ parameters in
+    #   flight. Defaults to +true+.
+    def initialize(client: nil, recursive: false, with_decryption: true)
+      @client = client || Aws::SSM::Client.new
+      @recursive = recursive
+      @with_decryption = with_decryption
+    end
+
+    # Fetch all parameters under a single SSM path.
+    #
+    # @param path [String] the SSM path to query (typically with a trailing slash).
+    # @return [Hash<String, String>] parameter basenames mapped to their values.
+    def call(path)
+      @client.get_parameters_by_path(
+        path: path, recursive: @recursive, with_decryption: @with_decryption
+      ).each_page.flat_map(&:parameters).to_h do |param|
+        [param.name.split("/").last, param.value]
+      end
+    end
+  end
+end

data/lib/strato_env/version.rb

@@ -0,0 +1,3 @@
+class StratoEnv
+  VERSION = "0.1.0".freeze
+end

data/lib/strato_env.rb

@@ -0,0 +1,85 @@
+require_relative "strato_env/version"
+require_relative "strato_env/ssm_fetcher"
+
+# StratoEnv loads layered configuration into ENV at boot.
+#
+# A loader composes one or more *paths* worth of key/value pairs and writes
+# them to +ENV+. The actual fetching of values is delegated to a *fetcher*,
+# any callable that takes a path and returns a +Hash<String, String>+. The
+# default fetcher is {SSMFetcher}, which reads from AWS SSM Parameter Store,
+# but you can inject any callable (a +Proc+, a lambda, a +Method+, or a class
+# with +#call+ defined). This makes it easy to:
+#
+# - Test loader logic without touching AWS by passing a stub fetcher.
+# - Add other backends (Secrets Manager, Vault, a YAML file) without changing
+#   the loader.
+# - Preview values before applying them via {#fetch}.
+#
+# When multiple paths are passed, they form layers: later paths override
+# earlier ones (right-most wins on collision).
+#
+# @example Default usage (SSM)
+#   StratoEnv.load(paths: ["/myapp/common/", "/myapp/web/"])
+#
+# @example Inspect values without touching ENV
+#   StratoEnv.fetch(paths: "/myapp/web/")
+#   # => { "DATABASE_URL" => "postgres://...", "REDIS_URL" => "redis://..." }
+#
+# @example Customise the SSM fetcher
+#   fetcher = StratoEnv::SSMFetcher.new(recursive: true)
+#   StratoEnv.new(fetcher: fetcher).load(paths: "/myapp/")
+#
+# @example Inject any callable as a fetcher
+#   yaml_fetcher = ->(path) { YAML.load_file(path) }
+#   StratoEnv.new(fetcher: yaml_fetcher).load(paths: "config/app.yml")
+class StratoEnv
+  # @param fetcher [#call] any callable that takes a path and returns a
+  #   +Hash<String, String>+. Anything that responds to +#call(path)+ works:
+  #   a +Proc+, a lambda, a +Method+ object, or a class with +#call+ defined.
+  #   Defaults to a new {SSMFetcher}.
+  def initialize(fetcher: SSMFetcher.new)
+    @fetcher = fetcher
+  end
+
+  # Fetch values for the given paths and write them to ENV.
+  #
+  # Equivalent to +apply(fetch(paths: paths))+.
+  #
+  # @param paths [String, Array<String>] one or more paths to load, in order.
+  #   Later paths override earlier ones on key collision.
+  # @return [Array<String>] the names of the ENV vars that were set.
+  def load(paths:)
+    apply(fetch(paths: paths))
+  end
+
+  # Fetch values for the given paths and return them as a merged hash without
+  # touching ENV. Useful for previewing, testing, or applying the values to
+  # somewhere other than ENV.
+  #
+  # @param paths [String, Array<String>] one or more paths to load, in order.
+  #   Later paths override earlier ones on key collision.
+  # @return [Hash<String, String>] merged key/value pairs across all paths.
+  def fetch(paths:)
+    Array(paths).map { |path| @fetcher.call(path) }.reduce({}, :merge)
+  end
+
+  # Write the given hash to ENV. Useful for composing with {#fetch} when you
+  # want custom logic between fetching and applying (e.g. diffing across
+  # namespaces and warning on overrides).
+  #
+  # @param values [Hash<String, String>] keys become ENV var names.
+  # @return [Array<String>] the names that were set in ENV.
+  def apply(values) = self.class.apply(values)
+
+  # @see #load
+  def self.load(paths:) = new.load(paths: paths)
+
+  # @see #fetch
+  def self.fetch(paths:) = new.fetch(paths: paths)
+
+  # @see #apply
+  def self.apply(values)
+    values.each { |name, value| ENV[name] = value }
+    values.keys
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: strato_env
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sami Samhuri
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ssm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: |
+  StratoEnv populates ENV from one or more AWS SSM Parameter Store paths.
+  Multiple paths form layers, with later paths overriding earlier ones, so
+  you can split common config from node-specific or environment-specific
+  overrides. No Rails dependency; works in Rails, Sinatra, Lambda, scripts,
+  or any Ruby boot process.
+email:
+- sami@samhuri.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/strato_env.rb
+- lib/strato_env/ssm_fetcher.rb
+- lib/strato_env/version.rb
+homepage: https://github.com/samsonjs/strato_env
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/samsonjs/strato_env/issues
+  changelog_uri: https://github.com/samsonjs/strato_env/releases
+  source_code_uri: https://github.com/samsonjs/strato_env
+  homepage_uri: https://github.com/samsonjs/strato_env
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Load layered AWS SSM Parameter Store values into ENV at boot
+test_files: []