gemstack-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b70d6f891a9e434329c1b9da8215f0c7bbb671c04ff5c8ffa14c4202141a286
+  data.tar.gz: 71e47589cca55dac9585312c3e2ba1d41dff1ba4d619e3560ceb81c00482397e
+SHA512:
+  metadata.gz: 37d1679eee802eb3dfe8fb14b1689877b7fed7e721f7129d7cee65a76d7cdec4ce3e5ad20979a17afda5af4ac55a7cc743ccbc6721dbc58abc1ca470aa53f15f
+  data.tar.gz: 253ea2f012ce68fa972873dc52b3188a5c36c3152770816ef60f2c228631f7712d513dbc235ea6b873ab901b02fa18531ba74e3d346508e62e21322ee80c3bd2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+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,26 @@
+# gemstack-core
+
+GemStack core: configuration, environment, logging, errors and plugins.
+
+The dependency-free foundation every GemStack module builds on.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Installed with the `gemstack` gem; you rarely need to add it yourself.
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/configuration.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-core`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/core.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+require "fileutils"
+require_relative "version"
+require_relative "settings"
+require_relative "environment"
+require_relative "dotenv"
+require_relative "errors"
+require_relative "error_mapping"
+require_relative "logger"
+require_relative "inflector"
+require_relative "plugins"
+
+module GemStack
+  # Root configuration. Modules add namespaces to it:
+  #   GemStack::Config.namespace(:http, GemStack::HTTP::Config)
+  class Config < Settings
+    setting :name, default: -> { File.basename(root) }
+    setting :root, default: -> { Dir.pwd }
+
+    # .env files loaded at boot, earlier files win. Real ENV always wins.
+    setting :env_files, default: lambda {
+      env = GemStack.env
+      env.local? ? [".env.#{env}.local", ".env.local", ".env.#{env}", ".env"] : []
+    }
+
+    # Root secret for signatures (storage URLs, derived keys). Production must
+    # set SECRET_KEY_BASE; development/test generate one in tmp/ (git-ignored).
+    setting :secret_key_base, default: lambda {
+      ENV.fetch("SECRET_KEY_BASE", nil) || (GemStack.env.local? ? GemStack.send(:local_secret) : nil)
+    }
+
+    # Keys (substring, case-insensitive) masked in logs and error output.
+    setting :filter_parameters, default: %w[password passwd secret token api_key apikey authorization cookie
+                                            credit_card card_number cvv ssn private_key]
+
+    namespace :logger do
+      setting :level, default: -> { ENV.fetch("GEMSTACK_LOG_LEVEL") { GemStack.env.production? ? "info" : "debug" } }
+      setting :format, default: -> { GemStack.env.local? ? :pretty : :json }
+      # Test logs are discarded unless GEMSTACK_LOG_LEVEL is set explicitly.
+      setting :output, default: -> { GemStack.env.test? && !ENV["GEMSTACK_LOG_LEVEL"] ? nil : $stdout }
+      # nil = colour when output is a terminal. `gemstack dev` sets
+      # GEMSTACK_LOG_COLOR=1 because child output goes through a pipe.
+      setting :color, default: -> { ENV["GEMSTACK_LOG_COLOR"]&.then { |v| v == "1" } }
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def env
+      @env ||= Environment.detect
+    end
+
+    def env=(name)
+      @env = name.is_a?(Environment) ? name : Environment.new(name)
+    end
+
+    def root
+      Pathname.new(config.root)
+    end
+
+    # First call in config/app.rb: sets the application root and loads .env
+    # files (development/test) before anything reads configuration or ENV.
+    def setup(root:)
+      config.root = root.to_s
+      load_env_files!
+      self
+    end
+
+    # Idempotent; real ENV variables are never overwritten.
+    def load_env_files!
+      files = config.env_files.map { |file| File.expand_path(file, config.root) }
+      return if @loaded_env_files == files
+
+      Dotenv.load(files)
+      @loaded_env_files = files
+    end
+
+    def logger
+      @logger ||= begin
+        settings = config.logger
+        Logger.new(settings.output, level: settings.level, format: settings.format,
+                                    filter: config.filter_parameters, color: settings.color)
+      end
+    end
+
+    attr_writer :logger
+
+    # A 32-byte key for one purpose, derived from secret_key_base, so a key
+    # leaked for one use (e.g. storage URLs) can't sign anything else.
+    def key_for(purpose)
+      secret = config.secret_key_base
+      if secret.to_s.empty?
+        raise ConfigurationError,
+              "SECRET_KEY_BASE is not set (generate one with: openssl rand -hex 64)"
+      end
+
+      OpenSSL::HMAC.digest("SHA256", secret, "gemstack:#{purpose}")
+    end
+
+    # Forget all process-level state. Intended for tests.
+    def reset!
+      @config = nil
+      @env = nil
+      @logger = nil
+      @loaded_env_files = nil
+    end
+
+    private
+
+    def local_secret
+      path = File.join(config.root, "tmp", "#{env}_secret")
+      return File.read(path).strip if File.file?(path)
+
+      FileUtils.mkdir_p(File.dirname(path))
+      SecureRandom.hex(64).tap { |secret| File.write(path, secret, perm: 0o600) }
+    end
+  end
+end

data/lib/gemstack/dotenv.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Minimal `.env` file support (see DECISIONS.md D-013).
+  #
+  # Supported syntax:
+  #   KEY=value
+  #   export KEY=value
+  #   KEY="double quoted, supports \n \t \" escapes"
+  #   KEY='single quoted, literal'
+  #   KEY=value # trailing comment (unquoted values only)
+  #   # full-line comment
+  #
+  # Variables already present in the environment are never overwritten: the
+  # real environment always wins over files.
+  module Dotenv
+    LINE = /\A\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*(.*)\z/
+    ESCAPES = { "n" => "\n", "t" => "\t", "r" => "\r", '"' => '"', "\\" => "\\" }.freeze
+
+    module_function
+
+    # Loads the given files (in order; earlier files take precedence) into env.
+    # Returns the hash of variables that were actually set.
+    def load(*files, env: ENV)
+      loaded = {}
+      files.flatten.each do |file|
+        next unless File.file?(file)
+
+        parse(File.read(file)).each do |key, value|
+          next if env.key?(key) || loaded.key?(key)
+
+          env[key] = value
+          loaded[key] = value
+        end
+      end
+      loaded
+    end
+
+    def parse(source)
+      source.each_line.with_object({}) do |raw, vars|
+        line = raw.chomp
+        next if line.strip.empty? || line.lstrip.start_with?("#")
+
+        match = LINE.match(line) or next
+        vars[match[1]] = parse_value(match[2].strip)
+      end
+    end
+
+    def parse_value(value)
+      case value[0]
+      when '"'
+        body = value[1..][/\A((?:[^"\\]|\\.)*)"/, 1] || value[1..]
+        body.gsub(/\\(.)/) { ESCAPES.fetch(::Regexp.last_match(1), "\\#{::Regexp.last_match(1)}") }
+      when "'"
+        value[1..][/\A([^']*)'/, 1] || value[1..]
+      else
+        value.sub(/\s+#.*\z/, "")
+      end
+    end
+  end
+end

data/lib/gemstack/environment.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GemStack
+  # The running environment: development, test, production, or any custom name.
+  #
+  #   GemStack.env.production?  # => false
+  #   GemStack.env.to_s         # => "development"
+  class Environment
+    KNOWN = %w[development test production].freeze
+
+    attr_reader :name
+
+    def self.detect(env = ENV)
+      new(env["GEMSTACK_ENV"] || env["RACK_ENV"] || "development")
+    end
+
+    def initialize(name)
+      @name = name.to_s.strip.downcase
+      raise ArgumentError, "environment name cannot be empty" if @name.empty?
+    end
+
+    def development? = name == "development"
+    def test? = name == "test"
+    def production? = name == "production"
+
+    # Anything that isn't development or test is treated like production for
+    # safety-related defaults (hiding error details, JSON logs, ...).
+    def local? = development? || test?
+
+    def to_s = name
+    def to_sym = name.to_sym
+    def ==(other) = name == other.to_s
+    alias eql? ==
+    def hash = name.hash
+    def inspect = "#<GemStack::Environment #{name}>"
+  end
+end

data/lib/gemstack/error_mapping.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Translates third-party exceptions into GemStack errors, so modules can
+  # give library errors an HTTP meaning without depending on the HTTP layer:
+  #
+  #   GemStack::ErrorMapping.register(Sequel::NoMatchingRow) { GemStack::NotFound.new }
+  #   GemStack::ErrorMapping.register(Stripe::CardError) { |e| GemStack::Error.new(e.message, status: 402, code: "card_declined") }
+  #
+  # The HTTP error renderer consults this registry before rendering. The most
+  # recently registered matching class wins, so applications can override
+  # module defaults.
+  module ErrorMapping
+    @mappings = []
+    @mutex = Mutex.new
+
+    class << self
+      def register(exception_class, &translator)
+        raise ArgumentError, "ErrorMapping.register needs a block" unless translator
+
+        @mutex.synchronize { @mappings.unshift([exception_class, translator]) }
+      end
+
+      def unregister(exception_class)
+        @mutex.synchronize { @mappings.reject! { |klass, _| klass == exception_class } }
+      end
+
+      # Returns the translated error, or the original exception if no mapping applies.
+      def translate(exception)
+        _, translator = @mappings.find { |klass, _| exception.is_a?(klass) }
+        return exception unless translator
+
+        translator.call(exception) || exception
+      end
+    end
+  end
+end

data/lib/gemstack/errors.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Base class for every GemStack error.
+  #
+  # Errors carry an HTTP-oriented *suggestion* (`status`, `code`) so that any
+  # module — including ones that know nothing about HTTP, such as a database
+  # adapter — can raise an error that the HTTP layer renders correctly. Any
+  # exception that responds to #status and #code is rendered this way, so
+  # applications can define their own errors without subclassing these.
+  class Error < StandardError
+    class << self
+      attr_writer :default_status, :default_code, :default_message
+
+      def default_status = @default_status || inherited_default(:default_status, 500)
+      def default_code = @default_code || inherited_default(:default_code, "internal_error")
+      def default_message = @default_message || inherited_default(:default_message, "Internal Server Error")
+
+      # Declares the status/code/message for an error class.
+      def status(status, code, message)
+        self.default_status = status
+        self.default_code = code
+        self.default_message = message
+      end
+
+      private
+
+      def inherited_default(name, fallback) = superclass.respond_to?(name) ? superclass.public_send(name) : fallback
+    end
+
+    attr_reader :status, :code, :details, :headers
+
+    # details: optional field => [messages] hash, rendered as `errors`.
+    # headers: extra response headers (e.g. "allow" for 405, "retry-after" for 429).
+    def initialize(message = nil, status: nil, code: nil, details: nil, headers: nil)
+      @status = status || self.class.default_status
+      @code = code || self.class.default_code
+      @details = details
+      @headers = headers || {}
+      super(message || self.class.default_message)
+    end
+
+    # Whether the message is safe to show to API clients. Server errors are
+    # not: their messages may contain internal information.
+    def expose_message? = status < 500
+  end
+
+  # Raised for invalid framework or application configuration.
+  class ConfigurationError < Error; end
+
+  class BadRequest < Error
+    status 400, "bad_request", "Bad Request"
+  end
+
+  class Unauthorized < Error
+    status 401, "unauthorized", "Unauthorized"
+  end
+
+  class Forbidden < Error
+    status 403, "forbidden", "Forbidden"
+  end
+
+  class NotFound < Error
+    status 404, "not_found", "Not Found"
+  end
+
+  class MethodNotAllowed < Error
+    status 405, "method_not_allowed", "Method Not Allowed"
+  end
+
+  class Conflict < Error
+    status 409, "conflict", "Conflict"
+  end
+
+  class PayloadTooLarge < Error
+    status 413, "payload_too_large", "Payload Too Large"
+  end
+
+  class UnsupportedMediaType < Error
+    status 415, "unsupported_media_type", "Unsupported Media Type"
+  end
+
+  class ValidationError < Error
+    status 422, "validation_failed", "Validation failed"
+
+    def initialize(message = nil, errors: {}, **)
+      super(message, details: errors, **)
+    end
+
+    def errors = details
+  end
+
+  class TooManyRequests < Error
+    status 429, "too_many_requests", "Too Many Requests"
+  end
+
+  class ServiceUnavailable < Error
+    status 503, "service_unavailable", "Service Unavailable"
+  end
+end

data/lib/gemstack/inflector.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module GemStack
+  # English inflections used by conventions (routes, generators, constants).
+  #
+  #   Inflector.pluralize("category")      # => "categories"
+  #   Inflector.camelize("inventory_item") # => "InventoryItem"
+  #   Inflector.underscore("InventoryItem")# => "inventory_item"
+  #
+  # Extend with Inflector.irregular("person", "people") or
+  # Inflector.uncountable("equipment") — typically in config/app.rb.
+  module Inflector
+    PLURALS = [
+      [/(quiz)\z/i, '\1zes'],
+      [/\A(ox)\z/i, '\1en'],
+      [/(matr|vert|ind)(?:ix|ex)\z/i, '\1ices'],
+      [/(x|ch|ss|sh|zz)\z/i, '\1es'],
+      [/([^aeiouy]|qu)y\z/i, '\1ies'],
+      [/(?:([^f])fe|([lr])f)\z/i, '\1\2ves'],
+      [/sis\z/i, "ses"],
+      [/([ti])um\z/i, '\1a'],
+      [/(buffal|tomat|potat|her|ech)o\z/i, '\1oes'],
+      [/(bu|mis|ga|alia|statu|stat|vir|octop|cact)us\z/i, '\1uses'],
+      [/s\z/i, "s"],
+      [/\z/, "s"]
+    ].freeze
+
+    SINGULARS = [
+      [/(quiz)zes\z/i, '\1'],
+      [/(matr)ices\z/i, '\1ix'],
+      [/(vert|ind)ices\z/i, '\1ex'],
+      [/\A(ox)en/i, '\1'],
+      [/(alias|status|bus|campus|virus|octopus|cactus)(es)?\z/i, '\1'],
+      [/(x|ch|ss|sh|zz)es\z/i, '\1'],
+      [/(m)ovies\z/i, '\1ovie'],
+      [/([^aeiouy]|qu)ies\z/i, '\1y'],
+      [/([lr])ves\z/i, '\1f'],
+      [/([^f])ves\z/i, '\1fe'],
+      [/(analy|ba|diagno|parenthe|progno|synop|the)ses\z/i, '\1sis'],
+      [/(buffal|tomat|potat|her|ech)oes\z/i, '\1o'],
+      [/([ti])a\z/i, '\1um'],
+      [/ss\z/i, "ss"],
+      [/s\z/i, ""]
+    ].freeze
+
+    DEFAULT_IRREGULARS = {
+      "person" => "people", "man" => "men", "woman" => "women", "child" => "children",
+      "mouse" => "mice", "goose" => "geese", "tooth" => "teeth", "foot" => "feet"
+    }.freeze
+
+    DEFAULT_UNCOUNTABLES = %w[equipment information rice money species series fish sheep deer news data].freeze
+
+    @irregulars = DEFAULT_IRREGULARS.dup
+    @uncountables = DEFAULT_UNCOUNTABLES.dup
+
+    class << self
+      def irregular(singular, plural)
+        @irregulars[singular.downcase] = plural.downcase
+      end
+
+      def uncountable(*words)
+        @uncountables.concat(words.flatten.map(&:downcase))
+      end
+
+      def pluralize(word)
+        inflect(word.to_s, @irregulars, PLURALS)
+      end
+
+      def singularize(word)
+        inflect(word.to_s, @irregulars.invert, SINGULARS)
+      end
+
+      # "inventory_item" / "inventory-item" => "InventoryItem";
+      # "admin/products" => "Admin::Products"
+      def camelize(term)
+        term.to_s.split("/").map do |part|
+          part.split(/[_-]/).map { |w| w[0] ? w[0].upcase + w[1..] : w }.join
+        end.join("::")
+      end
+
+      # "InventoryItem" => "inventory_item"; "Admin::Products" => "admin/products"
+      def underscore(term)
+        term.to_s.gsub("::", "/")
+            .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr("-", "_")
+            .downcase
+      end
+
+      def dasherize(term) = underscore(term).tr("_", "-")
+
+      # "inventory_item" => "Inventory item"
+      def humanize(term)
+        words = underscore(term).delete_suffix("_id").tr("_", " ")
+        words[0] ? words[0].upcase + words[1..] : words
+      end
+
+      # "inventory_items" => "InventoryItem"
+      def classify(term) = camelize(singularize(term.to_s))
+
+      # "InventoryItem" => "inventory_items"
+      def tableize(term) = pluralize(underscore(term))
+
+      private
+
+      # irregulars maps source form => target form (e.g. "person" => "people").
+      def inflect(word, irregulars, rules)
+        return word if word.empty?
+
+        prefix, last = split_last_word(word)
+        lower = last.downcase
+        return word if @uncountables.include?(lower) || irregulars.value?(lower)
+        return prefix + match_case(last, irregulars[lower]) if irregulars.key?(lower)
+
+        rules.each do |pattern, replacement|
+          return prefix + last.sub(pattern, replacement) if last.match?(pattern)
+        end
+        word
+      end
+
+      # Only the final word is inflected: "line_item" => ["line_", "item"],
+      # "LineItem" => ["Line", "Item"].
+      def split_last_word(word)
+        match = word.match(/\A(.*[_\-\s])([^_\-\s]+)\z/m) || word.match(/\A(.*[a-z\d])([A-Z][^A-Z]*)\z/)
+        match ? [match[1], match[2]] : ["", word]
+      end
+
+      def match_case(original, replacement)
+        original[0] == original[0].upcase ? replacement[0].upcase + replacement[1..] : replacement
+      end
+    end
+  end
+end

data/lib/gemstack/logger.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module GemStack
+  # Structured, thread-safe logger.
+  #
+  #   logger.info("request", method: "GET", path: "/api/products", status: 200)
+  #   logger.debug { "expensive #{computation}" }
+  #   logger.with(request_id: id).warn("slow query", ms: 812)
+  #
+  # Formats:
+  #   :pretty  12:00:01.123 INFO  request method=GET path=/api/products status=200
+  #   :json    {"time":"...","level":"info","msg":"request","method":"GET",...}
+  #
+  # Fields whose key matches a filter (e.g. "password", "token") are replaced
+  # with "[FILTERED]", recursively. It also answers the standard ::Logger
+  # methods (#info, #level=, #debug?, ...) so it can be handed to other gems.
+  class Logger
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }.freeze
+    LABELS = { debug: "DEBUG", info: "INFO ", warn: "WARN ", error: "ERROR", fatal: "FATAL" }.freeze
+    COLORS = { debug: 90, info: 36, warn: 33, error: 31, fatal: 35 }.freeze
+    FILTERED = "[FILTERED]"
+
+    attr_reader :level, :format, :context
+
+    def initialize(output = $stdout, level: :info, format: :pretty, filter: [], context: {}, color: nil, mutex: nil)
+      @output = output
+      # Log lines must appear when written, also when stdout is a pipe (e.g.
+      # under `gemstack dev` or a process manager) where Ruby would buffer them.
+      @output.sync = true if @output.respond_to?(:sync=)
+      self.level = level
+      @format = format.to_sym
+      @filter = Array(filter).map { |f| f.to_s.downcase }
+      @context = context
+      @color = color.nil? ? output.respond_to?(:tty?) && output.tty? : color
+      @mutex = mutex || Mutex.new
+    end
+
+    def level=(value)
+      value = value.to_s.downcase.to_sym
+      raise ArgumentError, "unknown log level #{value.inspect}" unless LEVELS.key?(value)
+
+      @level = value
+    end
+
+    # A child logger that adds fields to every entry. Shares output and lock.
+    def with(**fields)
+      self.class.new(@output, level: @level, format: @format, filter: @filter, context: @context.merge(fields),
+                              color: @color, mutex: @mutex)
+    end
+
+    LEVELS.each_key do |name|
+      define_method(name) { |message = nil, **fields, &block| log(name, message, fields, &block) }
+      define_method(:"#{name}?") { enabled?(name) }
+    end
+
+    def enabled?(severity) = @output && LEVELS.fetch(severity) >= LEVELS.fetch(@level)
+
+    # ::Logger compatibility: `add(severity_int, message)`.
+    def add(severity, message = nil, progname = nil, &)
+      name = LEVELS.key(severity) || :info
+      log(name, message || progname, {}, &)
+    end
+
+    def <<(message) = info(message.to_s.chomp)
+
+    def filter(fields)
+      return fields if @filter.empty?
+
+      fields.to_h do |key, value|
+        if filtered_key?(key) then [key, FILTERED]
+        elsif value.is_a?(Hash) then [key, filter(value)]
+        else [key, value]
+        end
+      end
+    end
+
+    private
+
+    def log(severity, message, fields)
+      return true unless enabled?(severity)
+
+      message = yield if message.nil? && block_given?
+      fields = filter(@context.empty? ? fields : @context.merge(fields))
+      line = @format == :json ? json_line(severity, message, fields) : pretty_line(severity, message, fields)
+      @mutex.synchronize { @output.write(line) }
+      true
+    rescue IOError, SystemCallError
+      true # never let logging take the application down
+    end
+
+    def filtered_key?(key)
+      key = key.to_s.downcase
+      @filter.any? { |f| key.include?(f) }
+    end
+
+    def json_line(severity, message, fields)
+      entry = { time: Time.now.utc.iso8601(3), level: severity, msg: message.to_s }
+      fields.each { |key, value| entry[key] = serializable(value) }
+      "#{JSON.generate(entry)}\n"
+    end
+
+    def pretty_line(severity, message, fields)
+      label = LABELS[severity]
+      label = "\e[#{COLORS[severity]}m#{label}\e[0m" if @color
+      pairs = fields.map { |key, value| "#{key}=#{pretty_value(value)}" }
+      [Time.now.strftime("%H:%M:%S.%L"), label, message, *pairs].join(" ") << "\n"
+    end
+
+    def pretty_value(value)
+      case value
+      when String then value.match?(/[\s"=]/) ? value.inspect : value
+      when nil then "nil"
+      when Hash, Array then JSON.generate(serializable(value))
+      else value.to_s
+      end
+    end
+
+    def serializable(value)
+      case value
+      when String, Integer, Float, true, false, nil then value
+      when Hash then value.transform_values { |v| serializable(v) }
+      when Array then value.map { |v| serializable(v) }
+      when Exception then { class: value.class.name, message: value.message }
+      else value.to_s
+      end
+    end
+  end
+end

data/lib/gemstack/plugins.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Registry through which optional modules hook into application boot
+  # without the core (or the umbrella gem) knowing about them in advance.
+  #
+  #   # inside a hypothetical gemstack-jobs gem:
+  #   GemStack::Plugins.register(:jobs) do |app|
+  #     app.config.http.middleware.use GemStack::Jobs::Middleware
+  #     app.on_shutdown { GemStack::Jobs.stop }
+  #   end
+  #
+  # Hooks run once per boot, after configuration files are loaded and before
+  # the application is built, in registration order.
+  module Plugins
+    Plugin = Struct.new(:name, :hook)
+
+    @registry = {}
+    @mutex = Mutex.new
+
+    class << self
+      def register(name, &hook)
+        raise ArgumentError, "plugin #{name.inspect} needs a block" unless hook
+
+        @mutex.synchronize { @registry[name.to_sym] = Plugin.new(name.to_sym, hook) }
+      end
+
+      def unregister(name) = @mutex.synchronize { @registry.delete(name.to_sym) }
+      def registered?(name) = @registry.key?(name.to_sym)
+      def names = @registry.keys
+      def each(&) = @registry.values.each(&)
+
+      def run(app)
+        each { |plugin| plugin.hook.call(app) }
+      end
+    end
+  end
+end

data/lib/gemstack/settings.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module GemStack
+  # A small DSL for declaring configuration with defaults.
+  #
+  #   class HTTPConfig < GemStack::Settings
+  #     setting :api_path, default: "/api"
+  #     setting :health_path, default: -> { "#{api_path}/health" }
+  #     namespace :cors do
+  #       setting :origins, default: []
+  #     end
+  #   end
+  #
+  # - A callable default is evaluated lazily, in the context of the settings
+  #   object, the first time it is read, and then memoized. This lets defaults
+  #   depend on ENV or on other settings.
+  # - Array/Hash defaults are duplicated per instance, so instances never share
+  #   mutable state.
+  # - Reading or writing an undeclared setting raises NoMethodError (with
+  #   Ruby's did_you_mean suggestions), so typos fail fast.
+  class Settings
+    class << self
+      def definitions
+        @definitions ||= superclass <= Settings ? superclass.definitions.dup : {}
+      end
+
+      def namespaces
+        @namespaces ||= superclass <= Settings ? superclass.namespaces.dup : {}
+      end
+
+      def setting(name, default: nil)
+        name = name.to_sym
+        definitions[name] = default
+        define_method(name) { read(name) }
+        define_method(:"#{name}=") { |value| @values[name] = value }
+        name
+      end
+
+      # Declares a nested settings group. Pass a Settings subclass, or a block
+      # that is evaluated in a new anonymous subclass. Modules use this to add
+      # their own namespace to GemStack::Config without core knowing about them.
+      def namespace(name, klass = nil, &)
+        name = name.to_sym
+        klass ||= Class.new(Settings, &)
+        namespaces[name] = klass
+        define_method(name) do |&configure|
+          group = (@groups[name] ||= klass.new)
+          configure&.call(group)
+          group
+        end
+        klass
+      end
+    end
+
+    def initialize
+      @values = {}
+      @groups = {}
+    end
+
+    def read(name)
+      return @values[name] if @values.key?(name)
+
+      default = self.class.definitions.fetch(name)
+      @values[name] =
+        case default
+        when Proc then instance_exec(&default)
+        when Array, Hash then default.dup
+        else default
+        end
+    end
+
+    def set?(name)
+      @values.key?(name.to_sym)
+    end
+
+    def settings
+      self.class.definitions.keys
+    end
+
+    def to_h
+      hash = settings.to_h { |name| [name, read(name)] }
+      self.class.namespaces.each_key { |name| hash[name] = public_send(name).to_h }
+      hash
+    end
+  end
+end

data/lib/gemstack/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GemStack
+  # All GemStack gems are released together under a single version.
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: The dependency-free foundation every GemStack module builds on.
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/core.rb
+- lib/gemstack/dotenv.rb
+- lib/gemstack/environment.rb
+- lib/gemstack/error_mapping.rb
+- lib/gemstack/errors.rb
+- lib/gemstack/inflector.rb
+- lib/gemstack/logger.rb
+- lib/gemstack/plugins.rb
+- lib/gemstack/settings.rb
+- lib/gemstack/version.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-core
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-core/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack core: configuration, environment, logging, errors and plugins'
+test_files: []