bindan 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41a496e6f91cd22b627b887d5b0cb209cd3c6d277dedbf527dd38c774d444273
+  data.tar.gz: 6dea83b8c98edfa91989d2b488180e250710336cfe7b6470e257cec75c292c89
+SHA512:
+  metadata.gz: 0ffd5b03d4a1c9a76c696a514fbaa5bac9d323820dc19c88229b0ba88c6e6e893b6bd6b2e8d1659d325e4f235f906b87d14e37741ed0ba7045e11bcf8be4dcf7
+  data.tar.gz: 5a46f6c97809b06dc6dc4aa7b75a2e5093059b71f6baeb6fd75450f303471b7f005fee21f995787866d2341b1440a1f3d5fedd8dcfb3be98e77f81e0bf000a0e

data/.editorconfig

@@ -0,0 +1,5 @@
+[*]
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true

data/.envrc

@@ -0,0 +1,2 @@
+export FIRESTORE_EMULATOR_HOST=localhost:8080
+export FIRESTORE_PROJECT_ID=project

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-03
+
+- Initial release
+
+## [0.0.0] - 2025-07-12
+
+- start project

data/LICENSE

@@ -0,0 +1,9 @@
+Copyright 2025 wtnabe
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,136 @@
+# Bindan
+[![Gem Version](https://badge.fury.io/rb/bindan.svg)](https://badge.fury.io/rb/bindan)
+[![CI](https://github.com/wtnabe/bindan/actions/workflows/main.yml/badge.svg)](https://github.com/wtnabe/bindan/actions/workflows/main.yml)
+
+Bindan is a Ruby gem for building single configuration object from various sources with providers (that is bundled  Google Cloud Storage and Firestore platform by default). It provides a flexible way to manage application settings, supporting lazy initialization and seamless switching between development (using emulators) and production (eg. actual GCP services) environments.
+
+## Features
+
+- **Environment Transparency**: Use the same code for development (with emulators) and production.
+- **Multiple Providers**: Fetch configuration from:
+  - Environment Variables
+  - Google Cloud Storage
+  - Google Cloud Firestore
+  - your custom provider
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bindan'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install bindan
+```
+
+## Usage
+
+Here is a basic example of how to use Bindan.
+
+### Dead Simple Use
+
+Envvar built-in provider does not need extra code.
+
+```ruby
+require "bindan"
+
+config = Bindan.configure do |c, pr|
+  c.database_host = pr.env["DATABASE_HOST"] || "localhost"
+end
+
+# unless $DATABASE_HOST environment variable
+puts config.database_host # => "localhost"
+```
+
+### with Multiple Providers
+
+in Gemfile
+
+```ruby
+gem "bindan"
+gem "google-cloud-storage"
+gem "google-cloud-firestore"
+```
+
+and
+
+```ruby
+require "bindan"
+
+# Define your configuration providers
+providers = {
+  env: Bindan::Provider::Envvar.new,
+  storage: Bindan::Provider::Storage.new(bucket: "my-config-bucket"),
+  firestore: Bindan::Provider::Firestore.new(collection: "app-settings")
+}
+
+# Configure Bindan
+config = Bindan.configure(providers: providers) do |c, pr|
+  # Define configuration keys and how they are loaded from providers and fallback
+  c.database_host = pr.env["DATABASE_HOST"] || "localhost"
+  c.api_key = pr.storage["api_key"]
+  c.feature_flags = pr.firestore["feature_flags_document"]
+end
+
+# Access your configuration values
+puts config.database_host # => "localhost" (or value from ENV["DATABASE_HOST"])
+puts config.api_key       # => (Value loaded from Google Cloud Storage)
+puts config.feature_flags # => (Value loaded from Firestore)
+```
+
+In the `configure` block, you define how each configuration key is mapped to a provider. The provider name is `providers` Hash key.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Prerequisites for Development
+
+This gem is designed to interacts with Google Cloud services as a first-class citizen. For local development and testing, it uses emulators. Please install the following tools:
+
+1.  **Google Cloud CLI:** [Installation the gcloud CLI](https://cloud.google.com/sdk/docs/install)
+2.  **Docker:** [Get Docker](https://docs.docker.com/get-docker/)
+3.  **Firestore Emulator:**
+    ```bash
+    gcloud components install cloud-firestore-emulator
+    ```
+4.  **fake-gcs-server:**
+    ```bash
+    docker pull fsouza/fake-gcs-server
+    ```
+
+### Custom Provider
+
+implement `[]` method.
+
+```ruby
+class CustomProvider
+  def [](key)
+    ...
+  end
+end
+```
+
+### Running Tests
+
+The test suite is configured to automatically start the emulators (including `fake-gcs-server` via Docker), run the tests against them, and shut them down. Simply run:
+
+```bash
+bundle exec rake spec
+```
+
+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/wtnabe/bindan.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create(:spec) do |t|
+  t.libs << "spec"
+  t.test_globs = "spec/**/*_spec.rb"
+  t.warning = false
+end
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/Steepfile

@@ -0,0 +1,17 @@
+# D = Steep::Diagnostic
+#
+target :lib do
+  signature "sig"
+
+  check "lib"                       # Directory name
+end
+
+# target :test do
+#   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
+#   signature "sig/test"              # Put RBS files for tests under `sig/test`
+#   check "test"                      # Type check Ruby scripts under `test`
+#
+#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+#
+#   # library "pathname"              # Standard libraries
+# end

data/compose.yml

@@ -0,0 +1,12 @@
+services:
+  storage:
+    image: fsouza/fake-gcs-server:latest
+    command: -scheme http -port 4443 -host 0.0.0.0
+    ports:
+      - "4443:4443"
+    healthcheck:
+      # The fake-gcs-server is ready when we can query the bucket list endpoint.
+      test: ["CMD", "curl", "-f", "http://localhost:4443/storage/v1/b"]
+      interval: 1s
+      timeout: 5s
+      retries: 20

data/lib/bindan/emulators/firestore_controller.rb

@@ -0,0 +1,152 @@
+require_relative "../error"
+require "fileutils"
+require "open3"
+require "socket"
+require "timeout"
+require "uri"
+
+module Bindan
+  module Emulator
+    #
+    # Represents and controls a single instance of the Google Cloud Firestore emulator process.
+    # This class encapsulates the logic for starting, stopping, and waiting for the emulator,
+    # separating process management from the test execution flow.
+    #
+    class FirestoreController
+      WAIT_TIMEOUT = 15 # seconds
+      INITIAL_BACKOFF_KEY_SEC = 0.1 # seconds
+      BACKOFF_MULTIPLIER = 1.5
+
+      class << self
+        #
+        # @return [Array<String, Integer>]
+        #
+        def host_and_port(host = nil, port = nil)
+          host, port = ENV["FIRESTORE_EMULATOR_HOST"].to_s.split(":") if ENV["FIRESTORE_EMULATOR_HOST"]
+
+          host ||= ENV["CI"] ? "0.0.0.0" : "localhost"
+          port ||= 8080
+
+          [host, port]
+        end
+
+        #
+        # Initiates the emulator process and returns a new instance.
+        #
+        # @param [String] import
+        # @param [String] export
+        # @param [String] host
+        # @param [Integer] port
+        # @param [bool] close_io
+        # @raise [Errno]
+        # @return [FirestoreEmulatorController] An instance to manage the emulator lifecycle.
+        #
+        def start(import: nil, export: nil, host: nil, port: nil, close_io: true)
+          host, port = host_and_port(host, port)
+
+          puts " Starting Firestore emulator ..." unless close_io
+          kill_process_if_already_exists(host: host, port: port, with_message: !close_io)
+
+          #
+          # This command is known to launch a background Java process and then exit.
+          # Trying keep process info with process group
+          #
+          cmd = "gcloud emulators firestore start --host-port=#{host}:#{port}"
+          cmd += " --import-data=#{import}" if import
+          cmd += " --export-on-exit=#{export}" if export
+          opts = close_io ? {out: "/dev/null", err: "/dev/null"} : {}
+          pid = Process.spawn(*cmd, pgroup: true, **opts) # steep:ignore
+
+          puts "   Emulator process initiated." unless close_io
+          new(pid, host, port)
+        end
+
+        #
+        # kill process group
+        #
+        # @param [Integer] pid
+        # @param [bool] with_message
+        # @return [void]
+        #
+        def stop(pid, with_message: true)
+          puts "\n=> Stopping Firestore emulator..." if with_message
+
+          begin
+            Process.kill("TERM", -pid)
+            Process.wait(-pid)
+          rescue Errno::ESRCH, Errno::ECHILD
+            # Process was already killed or doesn't exist, which is fine.
+          end
+
+          puts "   Emulator process terminated." if with_message
+        end
+
+        #
+        # @param [Integer] host
+        # @param [Integer] port
+        #
+        def kill_process_if_already_exists(host:, port:, with_message: true)
+          TCPSocket.new(host, port).close
+
+          # `lsof -Fg -i:PORT` returns PIDs of the process listening on the port.
+          process_ids, = Open3.capture3(*"lsof -Fg -g -s TCP:LISTEN -i :#{port}".split(" "))
+          process_group = process_ids.lines.map(&:chomp).find { |id| id =~ /^g([0-9]+)/ }
+
+          if process_group
+            id = process_group[1..].to_i # strip first letter
+            puts "   Found emulator process group #{id} on port #{port}. Terminating." if with_message
+            stop(id, with_message: false)
+          end
+        rescue Errno::ECONNREFUSED
+          # noop
+        end
+      end # of class methods
+
+      #
+      # @param [Integer] pid - process group id
+      #
+      def initialize(pid, host, port)
+        @pid = pid
+        @host = host
+        @port = port
+      end
+
+      #
+      # waits to accessable
+      #
+      # @raise [Timeout::Error] if the emulator does not become available within the configured timeout.
+      # @param [number] timeout
+      # @param [number] backoff
+      # @param [number] multiplier
+      # @return [void]
+      #
+      def wait_available(timeout: WAIT_TIMEOUT, backoff: INITIAL_BACKOFF_KEY_SEC, multiplier: BACKOFF_MULTIPLIER, with_message: true)
+        last_rescue_error = nil
+
+        puts "   Waiting for emulator to be ready on #{@host}:#{@port}..." if with_message
+        count = 1
+        Timeout.timeout(timeout) do
+          loop do
+            TCPSocket.new(@host, @port).close
+            puts "   Emulator is up and listening." if with_message
+            return
+          rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL => e
+            last_rescue_error = e
+            sleep backoff
+            count += 1
+            backoff *= multiplier**count
+          end
+        end
+      rescue Timeout::Error
+        raise last_rescue_error # steep:ignore
+      end
+
+      #
+      # @return [void]
+      #
+      def stop(with_message: true)
+        self.class.stop(@pid, with_message: with_message)
+      end
+    end
+  end
+end

data/lib/bindan/emulators/gcs_server_controller.rb

@@ -0,0 +1,119 @@
+require_relative "../error"
+require "fileutils"
+require "timeout"
+require "open3"
+
+module Bindan
+  module Emulator
+    class GcsServerController
+      class ContainerCannotOpenError < Error; end
+
+      CONTAINER_NAME = "gcs-server"
+      WAIT_TIMEOUT = 15 # seconds
+      INITIAL_BACKOFF_KEY_SEC = 0.1 # seconds
+      BACKOFF_MULTIPLIER = 1.5
+
+      class << self
+        #
+        # @raise [Errno]
+        # @param [String] folder
+        # @param [Integer] [port]
+        # @param [String] [name]
+        # @return [GcsServerController]
+        #
+        def start(folder:, port: 4443, name: CONTAINER_NAME, close_io: true)
+          FileUtils.mkdir_p(folder)
+          unless running?(name: name)
+            opts = close_io ? {out: "/dev/null", err: "/dev/null"} : {}
+            Process.spawn( # steep:ignore
+              *"docker run --rm --name #{name} -p #{port}:4443 -v #{folder}:/data fsouza/fake-gcs-server -scheme http".split(" "),
+              **opts
+            )
+          end
+
+          new(name: name, folder: folder)
+        end
+
+        #
+        # @raise [IOError]
+        # @param [String] name
+        # @return [bool]
+        #
+        def running?(name:)
+          _stdin, stdout, stderr, = Open3.popen3("docker container list -f name=#{name}")
+
+          begin
+            # container list not only headers
+            stdout.readlines.size > 1
+          rescue IOError => e
+            warn "in #{self}"
+            warn "   " + stderr.read
+            raise ContainerCannotOpenError.new e
+          end
+        end
+
+        #
+        # @param [String] name
+        # @raise [Errno]
+        # @return [void]
+        #
+        def stop(name:)
+          `docker container stop #{name}`
+        end
+      end # of class methods
+
+      #
+      # @param [String] name
+      # @param [String] folder
+      #
+      def initialize(name:, folder:)
+        @container_name = name
+        @folder = folder
+      end
+
+      #
+      # @return
+      #
+      def stop
+        self.class.stop(name: @container_name)
+      end
+
+      #
+      # @param [String] name
+      # @return [bool]
+      #
+      def running?
+        self.class.running?(name: @container_name)
+      end
+
+      #
+      # waits container to be running
+      #
+      # @raise [ContainerCannotOpenError] if the container does not become available within the configured timeout.
+      # @param [number] timeout
+      # @param [number] backoff
+      # @param [number] multiplier
+      # @return [void]
+      #
+      def wait_available(timeout: WAIT_TIMEOUT, backoff: INITIAL_BACKOFF_KEY_SEC, multiplier: BACKOFF_MULTIPLIER)
+        last_rescued_error = nil
+
+        count = 1
+        Timeout.timeout(timeout) do
+          loop do
+            if running?
+              return
+            end
+          rescue ContainerCannotOpenError => e
+            last_rescued_error = e
+            sleep backoff
+            count += 1
+            backoff *= multiplier**count
+          end
+        end
+      rescue Timeout::Error
+        raise last_rescued_error # steep:ignore
+      end
+    end
+  end
+end

data/lib/bindan/error.rb

@@ -0,0 +1,3 @@
+module Bindan
+  class Error < StandardError; end
+end

data/lib/bindan/providers/envvar.rb

@@ -0,0 +1,27 @@
+module Bindan
+  module Provider
+    class Envvar
+      #
+      # @param [Hash] env
+      # @param [Hash] options
+      #
+      def initialize(env = ENV.to_h, options = {})
+        @_env = env
+        @_options = options
+      end
+
+      #
+      # @raise KeyError
+      # @param [String] key
+      # @return [String]
+      #
+      def [](key)
+        if @_options[:raise_error]
+          @_env.fetch(key)
+        else
+          @_env[key]
+        end
+      end
+    end
+  end
+end

data/lib/bindan/providers/firestore.rb

@@ -0,0 +1,87 @@
+require_relative "../error"
+begin
+  require "google/cloud/firestore"
+rescue LoadError => e
+  warn e
+  module Google
+    module Cloud
+      class Firestore
+        def initialize(**kwargs)
+        end
+
+        def doc(*args)
+          Class.new do
+            def create(*args)
+            end
+
+            def get
+              Class.new do
+                def data
+                end
+              end.new
+            end
+          end.new
+        end
+      end
+    end
+  end
+end
+
+module Bindan
+  module Provider
+    class Firestore
+      class ColOrDocNotExist < Error; end
+
+      #
+      # @param [String] collection
+      # @param [bool] raise_error
+      # @param [Google::Cloud::Firestore] sdk
+      #
+      def initialize(collection = nil, project_id: nil, raise_error: false, sdk: ::Google::Cloud::Firestore, **kwargs)
+        if ENV["FIRESTORE_EMULATOR_HOST"]
+          project_id ||= "project"
+        end
+
+        @_options = {}
+        @collection = collection
+
+        @_options[:raise_error] = raise_error
+        @project_id = project_id
+
+        @_firestore = sdk.new(project_id: project_id, **kwargs)
+      end
+      attr_reader :project_id
+
+      #
+      # @param [Hash] pair
+      #
+      def _prepare(pair)
+        path, doc = pair.to_a.flatten
+
+        @_firestore.doc(path).create(doc)
+      end
+
+      #
+      # @raise ColOrDocNotExist
+      # @param [String] key
+      # @return [Hash]
+      #
+      def [](key)
+        doc_path =
+          if @collection.nil? && key.include?("/")
+            key
+          else
+            [@collection, key].join("/")
+          end
+
+        doc = @_firestore.doc(doc_path).get
+
+        if @_options[:raise_error] && !doc.data
+          raise ColOrDocNotExist.new doc_path
+        else
+          doc.data
+        end
+      end
+    end
+  end
+end