state_sync 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0168fcb451c250ca0603039b16d46b17549155e16220022d42659525492c583
+  data.tar.gz: 799020c89366e8c271eb64c403004f545fdc0703cf5ac6704c07c372a4676997
+SHA512:
+  metadata.gz: a6afe4b0bf9392cfc4f9335ad283fdf6995b4ffe395274a9e2ecee83a283c0ee358b5db0ffa4f71731e613874b6f395a2a3b586696f53d17c2b8fe94ed673719
+  data.tar.gz: 560ddef2c20ed4ff91388e2ede1353c4f2b0b4022478cb7389ec5dc49a28b81dc03b4f68c00381b35fb53c0e07f02da51c7282da4403260e2d0ef4af9dcdefa2

data/GITHUB.md

@@ -0,0 +1,127 @@
+# GitHub Setup for state_sync
+
+`state_sync` reads YAML files directly from a GitHub repository using the GitHub Contents API.
+
+---
+
+## Public repositories
+
+No token is required. You can omit `config.token` entirely.
+However, unauthenticated requests are rate-limited to **60 requests/hour** per IP.
+If you enable `auto_refresh` with a short interval, you will hit this limit quickly.
+It is recommended to always provide a token even for public repos (authenticated limit is 5,000/hour).
+
+---
+
+## Private repositories
+
+A GitHub token with read access to the repository is required.
+
+---
+
+## Creating a token
+
+### Option A — Fine-grained Personal Access Token (recommended)
+
+Fine-grained tokens let you limit access to specific repositories and specific permissions.
+
+1. Go to **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens**
+2. Click **Generate new token**
+3. Set a name (e.g. `state_sync`) and an expiration
+4. Under **Repository access**, select **Only select repositories** and pick the repo that holds your YAML files
+5. Under **Permissions → Repository permissions**, find **Contents** and set it to **Read-only**
+6. Click **Generate token** and copy it immediately — GitHub will not show it again
+
+### Option B — Classic Personal Access Token
+
+1. Go to **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)**
+2. Click **Generate new token (classic)**
+3. Set a note and expiration
+4. Select the **`repo`** scope (grants full read/write to private repos — use fine-grained tokens if you want narrower access)
+5. Click **Generate token** and copy it
+
+---
+
+## Storing the token safely
+
+Never hardcode a token in your source code. Use an environment variable:
+
+```bash
+# .env (not committed to git)
+GITHUB_TOKEN=ghp_your_token_here
+```
+
+Then reference it in your configuration:
+
+```ruby
+StateSync.configure do |config|
+  config.provider = :github
+  config.token    = ENV["GITHUB_TOKEN"]
+  config.repo     = "your-org/your-repo"
+end
+```
+
+If you use Rails credentials, you can also store it there:
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+github:
+  state_sync_token: ghp_your_token_here
+```
+
+```ruby
+config.token = Rails.application.credentials.dig(:github, :state_sync_token)
+```
+
+---
+
+## Rate limits
+
+| Authentication        | Requests per hour |
+|-----------------------|-------------------|
+| None (public repos)   | 60                |
+| Personal Access Token | 5,000             |
+
+If you enable `auto_refresh` with `auto_refresh_interval: 60` (every minute) and have 10 files loaded,
+that is 600 requests/hour — well within the authenticated limit but it will exceed the unauthenticated limit.
+Always use a token when `auto_refresh` is enabled.
+
+---
+
+## Examples
+
+### Without auto refresh
+
+Data is fetched once when the server starts. It does not change until the server restarts.
+
+```ruby
+StateSync.configure do |config|
+  config.provider     = :github
+  config.repo         = "your-org/your-repo"
+  config.token        = ENV["GITHUB_TOKEN"]
+  config.auto_refresh = false
+end
+
+customers = StateSync.load("config/customers.yml")
+customers["customer_ids"]   # => [1001, 1002, 1003]
+```
+
+### With auto refresh
+
+Data is fetched at startup and a background thread keeps it updated at the configured interval.
+
+```ruby
+StateSync.configure do |config|
+  config.provider         = :github
+  config.repo             = "your-org/your-repo"
+  config.token            = ENV["GITHUB_TOKEN"]
+  config.auto_refresh     = true
+  config.auto_refresh_interval = 300   # seconds
+end
+
+customers = StateSync.load("config/customers.yml")
+customers["customer_ids"]   # => always current
+```

data/GITLAB.md

@@ -0,0 +1,106 @@
+# GitLab Setup for state_sync
+
+`state_sync` reads YAML files directly from a GitLab project using the GitLab Repository Files API.
+
+---
+
+## Public projects
+
+No token is required for public projects. You can omit `config.token` entirely.
+A token is still recommended to avoid hitting rate limits, especially when `auto_refresh` is enabled.
+
+---
+
+## Private projects
+
+A GitLab personal access token with `read_repository` scope is required.
+
+---
+
+## Creating a token
+
+1. Go to **GitLab → Edit profile → Access tokens**
+2. Click **Add new token**
+3. Give it a name (e.g. `state_sync`) and set an expiry date
+4. Under **Select scopes**, check **`read_repository`**
+5. Click **Create personal access token** and copy it immediately — GitLab will not show it again
+
+---
+
+## Storing the token safely
+
+Never hardcode a token in your source code. Use an environment variable:
+
+```bash
+# .env (not committed to git)
+GITLAB_TOKEN=glpat_your_token_here
+```
+
+Then reference it in your configuration:
+
+```ruby
+StateSync.configure do |config|
+  config.provider = :gitlab
+  config.token    = ENV["GITLAB_TOKEN"]
+  config.repo     = "your-org/your-repo"
+end
+```
+
+If you use Rails credentials, you can also store it there:
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+gitlab:
+  state_sync_token: glpat_your_token_here
+```
+
+```ruby
+config.token = Rails.application.credentials.dig(:gitlab, :state_sync_token)
+```
+
+---
+
+## Rate limits
+
+GitLab rate limits vary by plan and instance. Files over 10 MB are limited to 5 requests/minute.
+Always use a token when `auto_refresh` is enabled.
+
+---
+
+## Examples
+
+### Without auto refresh
+
+Data is fetched once when the server starts. It does not change until the server restarts.
+
+```ruby
+StateSync.configure do |config|
+  config.provider     = :gitlab
+  config.repo         = "your-org/your-repo"
+  config.token        = ENV["GITLAB_TOKEN"]
+  config.auto_refresh = false
+end
+
+customers = StateSync.load("config/customers.yml")
+customers["customer_ids"]   # => [1001, 1002, 1003]
+```
+
+### With auto refresh
+
+Data is fetched at startup and a background thread keeps it updated at the configured interval.
+
+```ruby
+StateSync.configure do |config|
+  config.provider         = :gitlab
+  config.repo             = "your-org/your-repo"
+  config.token            = ENV["GITLAB_TOKEN"]
+  config.auto_refresh     = true
+  config.auto_refresh_interval = 300   # seconds
+end
+
+customers = StateSync.load("config/customers.yml")
+customers["customer_ids"]   # => always current
+```

data/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -0,0 +1,134 @@
+# state_sync
+
+A Ruby gem for fetching YAML-based feature flags and configuration from a GitHub or GitLab repository.
+Values are loaded at startup and can optionally be kept fresh in the background.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "state_sync"
+```
+
+Or install directly:
+
+```bash
+gem install state_sync
+```
+
+---
+
+## Configuration
+
+Token setup: [GITHUB.md](GITHUB.md) | [GITLAB.md](GITLAB.md)
+
+```ruby
+# config/initializers/state_sync.rb
+StateSync.configure do |config|
+  config.provider              = :github          # :github or :gitlab
+  config.repo                  = "your-org/your-repo"  # "owner/repo" on GitHub or GitLab
+  config.token                 = ENV["GITHUB_TOKEN"]   # optional for public repos
+  config.auto_refresh          = false            # true or false (default: false)
+  config.auto_refresh_interval = 300              # seconds, only required when auto_refresh is true
+end
+```
+
+---
+
+## Usage
+
+```ruby
+# Load a YAML file — fetches immediately on this line
+CUSTOMERS = StateSync.load("config/customers.yml")
+
+# Access data
+CUSTOMERS.data              # => {"customer_ids" => [1001, 1002, 1003], "feature_x" => true}
+CUSTOMERS["customer_ids"]   # => [1001, 1002, 1003]
+CUSTOMERS["feature_x"]      # => true
+
+# Force a manual refresh at any time
+CUSTOMERS.reload!
+```
+
+### Example YAML file
+
+```yaml
+customer_ids:
+  - 1001
+  - 1002
+  - 1003
+
+feature_x: true
+```
+
+### Loading multiple files
+
+You can load as many files as you need — each gets its own store with independent data and refresh cycle. Define them in your initializer and use them anywhere in your app:
+
+```ruby
+# config/initializers/state_sync.rb
+StateSync.configure do |config|
+  config.provider = :github
+  config.repo     = "your-org/your-repo"  # "owner/repo" on GitHub or GitLab
+  config.token    = ENV["GITHUB_TOKEN"]
+end
+
+CUSTOMERS       = StateSync.load("config/customers.yml")
+FEATURE_FLAGS   = StateSync.load("config/feature_flags.yml")
+PAYMENT_METHODS = StateSync.load("config/payment_methods.yml")
+PAYMENT_LIMITS  = StateSync.load("config/payment_limits.yml")
+```
+
+```ruby
+# Use anywhere in your app
+CUSTOMERS["customer_ids"]
+FEATURE_FLAGS["new_checkout_flow"]
+PAYMENT_METHODS["enabled"]
+PAYMENT_LIMITS["daily_limit"]
+```
+---
+
+## Error handling
+
+```ruby
+begin
+  flags = StateSync.load("config/flags.yml")
+rescue StateSync::ConfigurationError => e
+  # Missing or invalid configuration
+rescue StateSync::FetchError => e
+  # Network error, bad token, file not found, etc.
+end
+```
+
+---
+
+## Try it in IRB
+
+First install the gem:
+
+```bash
+gem install state_sync
+```
+
+Then start IRB and require the gem:
+
+```bash
+irb
+```
+
+```ruby
+require "state_sync"
+
+StateSync.configure do |config|
+  config.provider = :github
+  config.repo     = "spmarisa/state_sync_data"  # public repo, no token needed
+end
+
+customers = StateSync.load("allowed_customers.yml")
+customers.data
+customers["customer_ids"]
+
+# Force a refresh
+customers.reload!
+```

data/lib/state_sync/configuration.rb

@@ -0,0 +1,23 @@
+class StateSync::Configuration
+  PROVIDERS = %i[github gitlab].freeze
+
+  attr_accessor :provider, :repo, :token, :auto_refresh, :auto_refresh_interval
+
+  def initialize
+    @provider         = :github
+    @auto_refresh     = false
+    @auto_refresh_interval = 300
+  end
+
+  def validate!
+    unless PROVIDERS.include?(provider)
+      raise StateSync::ConfigurationError, "provider must be :github or :gitlab"
+    end
+
+    raise StateSync::ConfigurationError, "repo must be set (e.g. \"owner/repo\")" if repo.nil? || repo.strip.empty?
+
+    if auto_refresh && (auto_refresh_interval.nil? || auto_refresh_interval <= 0)
+      raise StateSync::ConfigurationError, "auto_refresh_interval must be a positive number of seconds when auto_refresh is true"
+    end
+  end
+end

data/lib/state_sync/errors.rb

@@ -0,0 +1,3 @@
+class StateSync::Error             < StandardError; end
+class StateSync::ConfigurationError < StateSync::Error; end
+class StateSync::FetchError         < StateSync::Error; end

data/lib/state_sync/fetchers/github_fetcher.rb

@@ -0,0 +1,52 @@
+require "net/http"
+require "uri"
+require "json"
+require "base64"
+
+class StateSync::GithubFetcher
+  API_BASE = "https://api.github.com"
+
+  def initialize(config)
+    @config = config
+  end
+
+  # Fetches raw file content (string) from GitHub.
+  # No ?ref= param — GitHub uses the repo's default branch automatically.
+  def fetch(path)
+    uri = URI("#{API_BASE}/repos/#{@config.repo}/contents/#{path}")
+
+    request = Net::HTTP::Get.new(uri)
+    request["Accept"]               = "application/vnd.github+json"
+    request["X-GitHub-Api-Version"] = "2022-11-28"
+    request["Authorization"]        = "Bearer #{@config.token}" if @config.token
+
+    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+      http.request(request)
+    end
+
+    handle_response(response, path)
+  end
+
+  private
+
+  def handle_response(response, path)
+    case response.code.to_i
+    when 200
+      json = JSON.parse(response.body)
+
+      if json["encoding"] == "base64"
+        Base64.decode64(json["content"])
+      else
+        raise StateSync::FetchError, "Unexpected encoding from GitHub: #{json["encoding"]}"
+      end
+    when 401
+      raise StateSync::FetchError, "GitHub authentication failed — check your github_token."
+    when 403
+      raise StateSync::FetchError, "GitHub access forbidden — ensure your token has 'Contents' read permission."
+    when 404
+      raise StateSync::FetchError, "File not found: '#{path}' in repo '#{@config.repo}'. Check the path and that the repo exists."
+    else
+      raise StateSync::FetchError, "GitHub API returned #{response.code}: #{response.body}"
+    end
+  end
+end

data/lib/state_sync/fetchers/gitlab_fetcher.rb

@@ -0,0 +1,44 @@
+require "net/http"
+require "uri"
+
+class StateSync::GitlabFetcher
+  API_BASE = "https://gitlab.com/api/v4"
+
+  def initialize(config)
+    @config = config
+  end
+
+  # Fetches raw file content from GitLab using the repository files raw endpoint.
+  # ref=HEAD always resolves to the project's default branch.
+  def fetch(path)
+    encoded_repo = URI.encode_www_form_component(@config.repo)
+    encoded_path = URI.encode_www_form_component(path)
+    uri = URI("#{API_BASE}/projects/#{encoded_repo}/repository/files/#{encoded_path}/raw?ref=HEAD")
+
+    request = Net::HTTP::Get.new(uri)
+    request["PRIVATE-TOKEN"] = @config.token if @config.token
+
+    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+      http.request(request)
+    end
+
+    handle_response(response, path)
+  end
+
+  private
+
+  def handle_response(response, path)
+    case response.code.to_i
+    when 200
+      response.body
+    when 401
+      raise StateSync::FetchError, "GitLab authentication failed — check your gitlab_token."
+    when 403
+      raise StateSync::FetchError, "GitLab access forbidden — ensure your token has 'read_repository' scope."
+    when 404
+      raise StateSync::FetchError, "File not found: '#{path}' in repo '#{@config.repo}'. Check the path and that the project exists."
+    else
+      raise StateSync::FetchError, "GitLab API returned #{response.code}: #{response.body}"
+    end
+  end
+end

data/lib/state_sync/store.rb

@@ -0,0 +1,63 @@
+require "yaml"
+
+# Holds the parsed contents of a single YAML file fetched from GitHub or GitLab.
+# On initialization it fetches the file immediately. If auto_refresh is
+# enabled a background thread keeps the data current at the configured interval.
+class StateSync::Store
+  def initialize(path)
+    @path    = path
+    @fetcher = fetcher_for(StateSync.configuration)
+    @mutex   = Mutex.new
+
+    fetch_and_cache
+
+    start_background_refresh if StateSync.configuration.auto_refresh
+  end
+
+  # Returns the parsed YAML data (Hash or Array depending on file content).
+  def data
+    @mutex.synchronize { @data }
+  end
+
+  # Shorthand key access when the YAML root is a Hash.
+  def [](key)
+    @mutex.synchronize { @data[key] }
+  end
+
+  # Force an immediate re-fetch from the configured provider.
+  def reload!
+    fetch_and_cache
+    self
+  end
+
+  private
+
+  def fetcher_for(config)
+    case config.provider
+    when :github then StateSync::GithubFetcher.new(config)
+    when :gitlab then StateSync::GitlabFetcher.new(config)
+    end
+  end
+
+  def fetch_and_cache
+    content = @fetcher.fetch(@path)
+    parsed  = YAML.safe_load(content)
+    @mutex.synchronize { @data = parsed }
+  end
+
+  def start_background_refresh
+    interval = StateSync.configuration.auto_refresh_interval
+
+    Thread.new do
+      Thread.current.daemon = true
+      loop do
+        sleep interval
+        begin
+          fetch_and_cache
+        rescue => e
+          warn "[StateSync] Failed to refresh '#{@path}': #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/state_sync/version.rb

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

data/lib/state_sync.rb

@@ -0,0 +1,29 @@
+require "state_sync/version"
+require "state_sync/errors"
+require "state_sync/configuration"
+require "state_sync/store"
+Dir[File.join(__dir__, "state_sync/fetchers/*.rb")].each { |f| require f }
+
+module StateSync
+  class << self
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Loads a YAML file from the configured provider (GitHub or GitLab) and returns a Store.
+    # The file is fetched immediately; if auto_refresh is enabled a background
+    # thread keeps it updated at the configured interval.
+    #
+    # Example:
+    #   customers = StateSync.load("config/customers.yml")
+    #   customers["allowed_ids"]  # => [1, 2, 3]
+    def load(path)
+      Store.new(path)
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: state_sync
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Phaneendra Marisa
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description:
+email:
+- phaneendra.marisa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- GITHUB.md
+- GITLAB.md
+- LICENSE
+- README.md
+- lib/state_sync.rb
+- lib/state_sync/configuration.rb
+- lib/state_sync/errors.rb
+- lib/state_sync/fetchers/github_fetcher.rb
+- lib/state_sync/fetchers/gitlab_fetcher.rb
+- lib/state_sync/store.rb
+- lib/state_sync/version.rb
+homepage: https://github.com/spmarisa/state_sync
+licenses:
+- WTFPL
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key:
+specification_version: 4
+summary: Fetch and auto-refresh YAML-based feature flags and config from a Git repository.
+test_files: []