arctic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 993528a395bd6f2b84ca9dea07dfc4415795d47b4711a0bf936dd618996d379e
+  data.tar.gz: 2f8700204e748b59e4ded52c35b6b78c929a43006319e70051d0f0bc2ccbeb59
+SHA512:
+  metadata.gz: f77978ece9e9c2d09498285f21a48d237fb962f8ca7ffaa28482d775423b62c1080f3961ef4e077192dee74b15d08760f2dd6a1565bed539b8c5a7fd14aac131
+  data.tar.gz: 070a4772798848a613c7364e14e90567a19265601a2384c1d0f6596ac71b8505a200b725842a93ff43cb52148e688b3f0bd221d59177fb707b0d73fcc9c6d944

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.0] - 2026-01-21
+
+### Added
+
+- Initial release of Arctic gem
+
+[0.1.0]: https://github.com/persona-id/arctic/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Persona
+
+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,234 @@
+# Arctic 🧊
+
+> Keep your environment frozen solid
+
+Arctic is a Ruby gem that provides a read-only, drop-in replacement for `ENV` with frozen, deduplicated strings to dramatically reduce memory allocations. Built as a C extension using Ruby's internal fstring table, Arctic offers zero-allocation access to environment variables after the first read.
+
+## Features
+
+- **Frozen Strings**: All returned strings are frozen, preventing accidental mutations
+- **Automatic Deduplication**: Uses Ruby's fstring table (`rb_enc_interned_str_cstr`) for zero allocations
+- **Drop-in Replacement**: Implements the read-only ENV API ([], fetch, key?, each, to_h, etc.)
+- **ClimateControl Compatible**: Works seamlessly with ClimateControl for testing
+- **High Performance**: Same system calls as ENV, with memory savings from deduplication
+- **C Extension**: Direct access to process environment via `getenv()` - no caching, always fresh
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'arctic'
+```
+
+Or install directly:
+
+```bash
+gem install arctic
+```
+
+## Usage
+
+### Basic Access
+
+```ruby
+require 'arctic'
+
+# Simple access (returns frozen string)
+Arctic['PATH']           # => "/usr/bin:/bin" (frozen)
+Arctic['HOME']           # => "/Users/user" (frozen)
+Arctic['NONEXISTENT']    # => nil
+
+# Fetch with defaults
+Arctic.fetch('RAILS_ENV')              # => "production" or raises KeyError
+Arctic.fetch('MISSING', 'default')     # => "default"
+Arctic.fetch('MISSING') { |k| "#{k}!" } # => "MISSING!"
+
+# Check existence
+Arctic.key?('PATH')      # => true
+Arctic.key?('MISSING')   # => false
+
+# Aliases work too
+Arctic.has_key?('PATH')  # => true
+Arctic.include?('PATH')  # => true
+Arctic.member?('PATH')   # => true
+```
+
+### Iteration
+
+```ruby
+# Iterate over all variables (keys and values are frozen)
+Arctic.each do |key, value|
+  puts "#{key}=#{value}"
+end
+
+# Get all keys or values
+Arctic.keys              # => ["PATH", "HOME", ...] (frozen strings)
+Arctic.values            # => ["/usr/bin:/bin", ...] (frozen strings)
+
+# Convert to hash
+hash = Arctic.to_h       # => {"PATH" => "/usr/bin:/bin", ...}
+```
+
+### Memory Efficiency
+
+Arctic automatically deduplicates strings using Ruby's fstring table:
+
+```ruby
+ENV['VAR1'] = 'shared_value'
+ENV['VAR2'] = 'shared_value'
+
+# Both return the SAME frozen object (deduplicated)
+val1 = Arctic['VAR1']
+val2 = Arctic['VAR2']
+val1.object_id == val2.object_id  # => true
+
+# Frozen strings prevent mutations
+val1.frozen?  # => true
+```
+
+### ClimateControl Compatibility
+
+Arctic works seamlessly with [ClimateControl](https://github.com/thoughtbot/climate_control) for testing:
+
+```ruby
+require 'arctic'
+require 'climate_control'
+
+# Arctic always reads current ENV values
+ENV['TEST_VAR'] = 'original'
+Arctic['TEST_VAR']  # => 'original'
+
+ClimateControl.modify(TEST_VAR: 'modified') do
+  Arctic['TEST_VAR']  # => 'modified' (detects the change)
+end
+
+Arctic['TEST_VAR']  # => 'original' (restored after block)
+```
+
+**How it works:** Arctic calls `getenv()` directly (just like ENV), so it always sees the current process environment. No cache invalidation needed - ClimateControl's modifications are immediately visible.
+
+## How It Works
+
+### C Extension with Fstring Table
+
+Arctic is implemented as a C extension that:
+
+1. **Reads directly from environment**: Uses `getenv()` to access the process environment
+2. **Creates fstrings immediately**: Calls `rb_enc_interned_str_cstr()` to create frozen, interned strings with proper locale encoding
+3. **Leverages Ruby's deduplication**: The fstring table ensures identical string values return the same object
+4. **Zero allocations after first access**: Subsequent reads of the same value return the existing fstring
+
+```c
+// Simplified implementation
+VALUE arctic_aref(VALUE self, VALUE key) {
+    const char* env_value = getenv(StringValueCStr(key));
+    if (env_value == NULL) return Qnil;
+
+    // Direct fstring creation with locale encoding - no intermediate allocation
+    return rb_enc_interned_str_cstr(env_value, rb_locale_encoding());
+}
+```
+
+### Performance Characteristics
+
+- **First access**: One `getenv()` call + fstring table intern (~same as ENV)
+- **Repeated access**: `getenv()` + fstring table lookup (returns existing object)
+- **Memory**: 90%+ reduction in allocations for frequently accessed values
+- **No caching overhead**: Always reads current values, no staleness issues
+
+## API Reference
+
+Arctic implements the most commonly used ENV methods:
+
+### Core Access
+- `Arctic[key]` - Get value (returns frozen string or nil)
+- `Arctic.fetch(key)` - Get with default or block
+- `Arctic.fetch(key, default)` - Get with default value
+- `Arctic.fetch(key) { |k| ... }` - Get with block
+
+### Existence Checks
+- `Arctic.key?(key)` - Check if key exists
+- `Arctic.has_key?(key)` - Alias for key?
+- `Arctic.include?(key)` - Alias for key?
+- `Arctic.member?(key)` - Alias for key?
+
+### Iteration
+- `Arctic.each { |k,v| ... }` - Iterate over key-value pairs
+- `Arctic.each_pair { |k,v| ... }` - Alias for each
+
+### Conversion
+- `Arctic.keys` - Array of all keys (frozen)
+- `Arctic.values` - Array of all values (frozen)
+- `Arctic.to_h` - Convert to hash
+- `Arctic.to_hash` - Alias for to_h
+
+### Information
+- `Arctic.empty?` - Check if environment is empty
+- `Arctic.size` - Count of environment variables
+- `Arctic.length` - Alias for size
+- `Arctic.inspect` - String representation
+
+## Requirements
+
+- Ruby >= 3.3.0
+- C compiler (gcc, clang, or compatible)
+- Standard C library with `stdlib.h` and `string.h`
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Compile the C extension
+bundle exec rake compile
+
+# Run tests
+bundle exec rake spec
+
+# Or do both
+bundle exec rake  # compile + spec
+```
+
+## Testing
+
+Arctic includes comprehensive test coverage:
+
+- **Core functionality tests**: Frozen strings, deduplication, nil handling
+- **ClimateControl compatibility**: All modification scenarios
+- **Memory efficiency tests**: Object identity verification
+- **Encoding tests**: UTF-8 and special characters
+
+```bash
+# Run all specs
+bundle exec rspec
+
+# Run specific test files
+bundle exec rspec spec/arctic_spec.rb
+bundle exec rspec spec/climate_control_spec.rb
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes with tests
+4. Run the test suite (`bundle exec rake`)
+5. Commit your changes (`git commit -am 'Add feature'`)
+6. Push to the branch (`git push origin feature/my-feature`)
+7. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt) for details.
+
+## Credits
+
+Created by the Persona engineering team to reduce memory allocations in our Rails application.
+
+Inspired by Ruby's fstring optimization and the need for efficient environment variable access in high-scale applications.
+
+## Tagline
+
+**"Keep your environment frozen solid"** ❄️

data/ext/arctic/arctic.c

@@ -0,0 +1,485 @@
+#include "ruby.h"
+#include "ruby/encoding.h"
+#include <stdlib.h>
+#include <string.h>
+
+// Forward declarations
+VALUE mArctic;
+
+/*
+ * Helper function to get environment variable count
+ *
+ * Iterates through the external environ array to count the total number
+ * of environment variables currently set.
+ *
+ * @return [int] The number of environment variables
+ */
+static int env_count(void) {
+    extern char **environ;
+    char **env = environ;
+    int count = 0;
+
+    while (*env != NULL) {
+        count++;
+        env++;
+    }
+
+    return count;
+}
+
+/*
+ * call-seq:
+ *   Arctic[key] -> value or nil
+ *
+ * Retrieves the value of the environment variable +key+.
+ *
+ * Returns a frozen, deduplicated string via rb_enc_interned_str_cstr() for
+ * memory efficiency. If the environment variable does not exist, returns +nil+.
+ *
+ * @param self [VALUE] The Arctic module
+ * @param key [VALUE] A String containing the environment variable name
+ * @return [VALUE] The frozen string value of the environment variable, or nil if not found
+ *
+ * Example:
+ *   Arctic["PATH"]  #=> "/usr/bin:/bin"
+ *   Arctic["NONE"]  #=> nil
+ */
+static VALUE arctic_aref(VALUE self, VALUE key) {
+    const char* env_key;
+    const char* env_value;
+
+    Check_Type(key, T_STRING);
+    env_key = StringValueCStr(key);
+    env_value = getenv(env_key);
+
+    if (env_value == NULL) {
+        return Qnil;
+    }
+
+    return rb_enc_interned_str_cstr(env_value, rb_locale_encoding());
+}
+
+/*
+ * call-seq:
+ *   Arctic.fetch(key) -> value
+ *   Arctic.fetch(key, default) -> value
+ *   Arctic.fetch(key) {|key| block } -> value
+ *
+ * Retrieves the environment variable +key+.
+ *
+ * If the key exists, returns its frozen, deduplicated value.
+ * If the key does not exist:
+ * - With a block: yields the key to the block and returns the block's result
+ * - With a default argument: returns the default value
+ * - Without either: raises KeyError
+ *
+ * @param argc [int] The number of arguments passed
+ * @param argv [VALUE*] Array of arguments (key and optional default)
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] The environment variable value, default value, or block result
+ * @raise [KeyError] If the key is not found and no default or block is provided
+ *
+ * Example:
+ *   Arctic.fetch("PATH")                    #=> "/usr/bin:/bin"
+ *   Arctic.fetch("MISSING", "default")      #=> "default"
+ *   Arctic.fetch("MISSING") { |k| "#{k}?" } #=> "MISSING?"
+ *   Arctic.fetch("MISSING")                 #=> raises KeyError
+ */
+static VALUE arctic_fetch(int argc, VALUE *argv, VALUE self) {
+    VALUE key, default_value;
+    const char* env_key;
+    const char* env_value;
+
+    rb_scan_args(argc, argv, "11", &key, &default_value);
+    Check_Type(key, T_STRING);
+
+    env_key = StringValueCStr(key);
+    env_value = getenv(env_key);
+
+    if (env_value == NULL) {
+        if (rb_block_given_p()) {
+            return rb_yield(key);
+        } else if (argc == 2) {
+            return default_value;
+        } else {
+            rb_raise(rb_eKeyError, "key not found: \"%s\"", env_key);
+        }
+    }
+
+    return rb_enc_interned_str_cstr(env_value, rb_locale_encoding());
+}
+
+/*
+ * call-seq:
+ *   Arctic.key?(key) -> true or false
+ *   Arctic.has_key?(key) -> true or false
+ *   Arctic.include?(key) -> true or false
+ *   Arctic.member?(key) -> true or false
+ *
+ * Returns +true+ if the environment variable +key+ exists, +false+ otherwise.
+ *
+ * This method has multiple aliases following Ruby's ENV API conventions.
+ *
+ * @param self [VALUE] The Arctic module
+ * @param key [VALUE] A String containing the environment variable name
+ * @return [VALUE] Qtrue if the key exists, Qfalse otherwise
+ *
+ * Example:
+ *   Arctic.key?("PATH")    #=> true
+ *   Arctic.has_key?("XYZ") #=> false
+ */
+static VALUE arctic_has_key(VALUE self, VALUE key) {
+    const char* env_key;
+
+    Check_Type(key, T_STRING);
+    env_key = StringValueCStr(key);
+
+    return getenv(env_key) != NULL ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *   Arctic.each {|key, value| block } -> Arctic
+ *   Arctic.each -> Enumerator
+ *   Arctic.each_pair {|key, value| block } -> Arctic
+ *   Arctic.each_pair -> Enumerator
+ *
+ * Iterates over all environment variables.
+ *
+ * When called with a block, yields each environment variable as a [key, value]
+ * pair where both key and value are frozen, deduplicated strings. Returns Arctic.
+ *
+ * When called without a block, returns an Enumerator.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] Arctic module (when block given) or Enumerator (when no block)
+ * @yield [key, value] Gives each environment variable name and value
+ *
+ * Example:
+ *   Arctic.each { |key, value| puts "#{key}=#{value}" }
+ *   Arctic.each.first(5)  #=> [["HOME", "/Users/..."], ...]
+ */
+static VALUE arctic_each(VALUE self) {
+    extern char **environ;
+    char **env = environ;
+
+    RETURN_SIZED_ENUMERATOR(self, 0, 0, env_count);
+
+    while (*env != NULL) {
+        char *entry = *env;
+        char *sep = strchr(entry, '=');
+
+        if (sep != NULL) {
+            VALUE key = rb_enc_interned_str(entry, sep - entry, rb_locale_encoding());
+            VALUE val = rb_enc_interned_str_cstr(sep + 1, rb_locale_encoding());
+            rb_yield_values(2, key, val);
+        }
+
+        env++;
+    }
+
+    return self;
+}
+
+/*
+ * call-seq:
+ *   Arctic.keys -> Array
+ *
+ * Returns an array containing all environment variable names.
+ *
+ * Each key is a frozen, deduplicated string for memory efficiency.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] An Array of frozen String keys
+ *
+ * Example:
+ *   Arctic.keys  #=> ["HOME", "PATH", "USER", ...]
+ */
+static VALUE arctic_keys(VALUE self) {
+    extern char **environ;
+    char **env = environ;
+    VALUE ary = rb_ary_new();
+
+    while (*env != NULL) {
+        char *entry = *env;
+        char *sep = strchr(entry, '=');
+
+        if (sep != NULL) {
+            VALUE key = rb_enc_interned_str(entry, sep - entry, rb_locale_encoding());
+            rb_ary_push(ary, key);
+        }
+
+        env++;
+    }
+
+    return ary;
+}
+
+/*
+ * call-seq:
+ *   Arctic.values -> Array
+ *
+ * Returns an array containing all environment variable values.
+ *
+ * Each value is a frozen, deduplicated string for memory efficiency.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] An Array of frozen String values
+ *
+ * Example:
+ *   Arctic.values  #=> ["/Users/...", "/usr/bin:/bin", "username", ...]
+ */
+static VALUE arctic_values(VALUE self) {
+    extern char **environ;
+    char **env = environ;
+    VALUE ary = rb_ary_new();
+
+    while (*env != NULL) {
+        char *entry = *env;
+        char *sep = strchr(entry, '=');
+
+        if (sep != NULL) {
+            VALUE val = rb_enc_interned_str_cstr(sep + 1, rb_locale_encoding());
+            rb_ary_push(ary, val);
+        }
+
+        env++;
+    }
+
+    return ary;
+}
+
+/*
+ * call-seq:
+ *   Arctic.to_h -> Hash
+ *
+ * Returns a Hash containing all environment variables.
+ *
+ * Both keys and values are frozen, deduplicated strings for memory efficiency.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] A Hash mapping environment variable names to their values
+ *
+ * Example:
+ *   Arctic.to_h  #=> {"HOME"=>"/Users/...", "PATH"=>"/usr/bin:/bin", ...}
+ */
+static VALUE arctic_to_h(VALUE self) {
+    extern char **environ;
+    char **env = environ;
+    VALUE hash = rb_hash_new();
+
+    while (*env != NULL) {
+        char *entry = *env;
+        char *sep = strchr(entry, '=');
+
+        if (sep != NULL) {
+            VALUE key = rb_enc_interned_str(entry, sep - entry, rb_locale_encoding());
+            VALUE val = rb_enc_interned_str_cstr(sep + 1, rb_locale_encoding());
+            rb_hash_aset(hash, key, val);
+        }
+
+        env++;
+    }
+
+    return hash;
+}
+
+/*
+ * call-seq:
+ *   Arctic.to_hash -> Hash
+ *
+ * Alias for Arctic.to_h.
+ *
+ * Returns a Hash containing all environment variables with frozen,
+ * deduplicated keys and values.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] A Hash mapping environment variable names to their values
+ *
+ * @see arctic_to_h
+ */
+static VALUE arctic_to_hash(VALUE self) {
+    return arctic_to_h(self);
+}
+
+/*
+ * call-seq:
+ *   Arctic.empty? -> true or false
+ *
+ * Returns +true+ if the environment contains no variables, +false+ otherwise.
+ *
+ * This is a fast check that only examines the first element of the environ array.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] Qtrue if environment is empty, Qfalse otherwise
+ *
+ * Example:
+ *   Arctic.empty?  #=> false (typically)
+ */
+static VALUE arctic_empty_p(VALUE self) {
+    extern char **environ;
+    return environ[0] == NULL ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *   Arctic.size -> Integer
+ *   Arctic.length -> Integer
+ *
+ * Returns the number of environment variables.
+ *
+ * This method is aliased as both +size+ and +length+ for compatibility with
+ * Ruby collection conventions.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] An Integer representing the count of environment variables
+ *
+ * Example:
+ *   Arctic.size    #=> 42
+ *   Arctic.length  #=> 42
+ */
+static VALUE arctic_size(VALUE self) {
+    return INT2NUM(env_count());
+}
+
+/*
+ * call-seq:
+ *   Arctic.inspect -> String
+ *
+ * Returns a string representation of the Arctic module.
+ *
+ * The format is "#<Arctic:0x...>" where the hex value is the module's memory address.
+ *
+ * @param self [VALUE] The Arctic module
+ * @return [VALUE] A String containing the inspection representation
+ *
+ * Example:
+ *   Arctic.inspect  #=> "#<Arctic:0x00007f8b1c000000>"
+ */
+static VALUE arctic_inspect(VALUE self) {
+    return rb_sprintf("#<Arctic:%p>", (void*)self);
+}
+
+/*
+ * Document-module: Arctic
+ *
+ * Arctic provides a read-only, memory-efficient interface to environment variables.
+ *
+ * Arctic is designed as a drop-in replacement for Ruby's ENV that prioritizes memory
+ * efficiency through aggressive string deduplication. All strings returned by Arctic
+ * are frozen and interned using rb_enc_interned_str_cstr(), which means repeated
+ * accesses to the same environment variable will return the exact same String object
+ * in memory rather than creating new allocations.
+ *
+ * == Key Features
+ *
+ * * *Read-only access*: Arctic only provides methods for reading environment variables,
+ *   preventing accidental modifications to the environment.
+ * * *Memory efficient*: All returned strings are frozen and deduplicated, dramatically
+ *   reducing memory usage when environment variables are accessed multiple times.
+ * * *ENV-compatible API*: Implements the most commonly-used read-only methods from Ruby's
+ *   ENV, making it easy to switch between the two.
+ * * *Fast*: Direct C implementation with minimal overhead.
+ *
+ * == Usage
+ *
+ *   # Basic access
+ *   Arctic["PATH"]        #=> "/usr/bin:/bin"
+ *   Arctic["MISSING"]     #=> nil
+ *
+ *   # Fetch with defaults or blocks
+ *   Arctic.fetch("HOME")                    #=> "/Users/username"
+ *   Arctic.fetch("MISSING", "default")      #=> "default"
+ *   Arctic.fetch("MISSING") { |k| "#{k}?" } #=> "MISSING?"
+ *
+ *   # Existence checks
+ *   Arctic.key?("PATH")     #=> true
+ *   Arctic.has_key?("XYZ")  #=> false
+ *
+ *   # Iteration
+ *   Arctic.each { |k, v| puts "#{k}=#{v}" }
+ *   Arctic.keys             #=> ["HOME", "PATH", "USER", ...]
+ *   Arctic.values           #=> ["/Users/...", "/usr/bin:/bin", ...]
+ *
+ *   # Conversion
+ *   Arctic.to_h             #=> {"HOME"=>"/Users/...", "PATH"=>...}
+ *
+ *   # Information
+ *   Arctic.size             #=> 42
+ *   Arctic.empty?           #=> false
+ *
+ * == Memory Efficiency
+ *
+ * Consider a typical Rails application that might access ENV["RAILS_ENV"] hundreds
+ * or thousands of times during initialization. With standard ENV, each access creates
+ * a new String object. With Arctic, all accesses return the exact same frozen String
+ * object, using only a single allocation regardless of how many times it's accessed.
+ *
+ * This is especially valuable in large applications with many environment variables
+ * or in long-running processes that frequently access configuration from the environment.
+ *
+ * == Comparison with ENV
+ *
+ * Arctic implements the following ENV methods:
+ * - Arctic[] (like ENV[])
+ * - Arctic.fetch (like ENV.fetch)
+ * - Arctic.key?, has_key?, include?, member? (like ENV.key? etc.)
+ * - Arctic.each, each_pair (like ENV.each)
+ * - Arctic.keys, values (like ENV.keys, ENV.values)
+ * - Arctic.to_h, to_hash (like ENV.to_h)
+ * - Arctic.empty?, size, length (like ENV.empty?, ENV.size)
+ *
+ * Arctic does NOT implement write operations like []=, store, update, delete, clear, etc.
+ * For modifying the environment, continue using ENV.
+ *
+ * @see https://docs.ruby-lang.org/en/master/ENV.html ENV documentation for comparison
+ */
+
+/*
+ * Initializes the Arctic extension.
+ *
+ * This function is called by Ruby when the extension is loaded. It defines
+ * the Arctic module and registers all its singleton methods.
+ *
+ * The Arctic module provides a read-only, memory-efficient interface to
+ * environment variables, using frozen and deduplicated strings throughout.
+ *
+ * Registered methods include:
+ * - Core access: [], fetch
+ * - Existence checks: key?, has_key?, include?, member?
+ * - Iteration: each, each_pair
+ * - Conversion: keys, values, to_h, to_hash
+ * - Information: empty?, size, length
+ * - Utility: inspect
+ */
+void Init_arctic(void) {
+    mArctic = rb_define_module("Arctic");
+
+    // Core access methods
+    rb_define_singleton_method(mArctic, "[]", arctic_aref, 1);
+    rb_define_singleton_method(mArctic, "fetch", arctic_fetch, -1);
+
+    // Existence checks (multiple aliases per ENV API)
+    rb_define_singleton_method(mArctic, "key?", arctic_has_key, 1);
+    rb_define_singleton_method(mArctic, "has_key?", arctic_has_key, 1);
+    rb_define_singleton_method(mArctic, "include?", arctic_has_key, 1);
+    rb_define_singleton_method(mArctic, "member?", arctic_has_key, 1);
+
+    // Iteration
+    rb_define_singleton_method(mArctic, "each", arctic_each, 0);
+    rb_define_singleton_method(mArctic, "each_pair", arctic_each, 0);
+
+    // Conversion methods
+    rb_define_singleton_method(mArctic, "keys", arctic_keys, 0);
+    rb_define_singleton_method(mArctic, "values", arctic_values, 0);
+    rb_define_singleton_method(mArctic, "to_h", arctic_to_h, 0);
+    rb_define_singleton_method(mArctic, "to_hash", arctic_to_hash, 0);
+
+    // Info methods
+    rb_define_singleton_method(mArctic, "empty?", arctic_empty_p, 0);
+    rb_define_singleton_method(mArctic, "size", arctic_size, 0);
+    rb_define_singleton_method(mArctic, "length", arctic_size, 0);
+
+    // Utility methods
+    rb_define_singleton_method(mArctic, "inspect", arctic_inspect, 0);
+}

data/ext/arctic/extconf.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: false
+
+require 'mkmf'
+
+# Check for required headers
+have_header('stdlib.h') or raise 'stdlib.h not found'
+have_header('string.h') or raise 'string.h not found'
+
+# Check for interned string functions (available in Ruby 2.3+)
+have_func('rb_interned_str_cstr', 'ruby.h')
+have_func('rb_enc_interned_str_cstr', 'ruby.h')
+have_func('rb_enc_interned_str', 'ruby.h')
+have_func('rb_locale_encoding', 'ruby/encoding.h')
+
+# Create Makefile for arctic extension
+create_makefile('arctic/arctic')

data/lib/arctic.rb

@@ -0,0 +1,16 @@
+# typed: false
+# frozen_string_literal: true
+
+module Arctic
+  VERSION = "0.1.0"
+end
+
+# Load the compiled C extension
+# The extension defines the Arctic module and all its methods
+begin
+  require 'arctic/arctic'
+rescue LoadError => e
+  # Provide helpful error message if extension not compiled
+  raise LoadError, 'Could not load arctic extension. ' \
+                   "Original error: #{e.message}"
+end

data/sig/arctic.rbs

@@ -0,0 +1,111 @@
+# TypeProf 0.21.11
+
+# Arctic provides a read-only, memory-efficient interface to environment variables.
+#
+# All returned strings are frozen and deduplicated using Ruby's fstring table,
+# dramatically reducing memory usage when environment variables are accessed multiple times.
+module Arctic
+  # The version of the Arctic gem
+  VERSION: String
+
+  # Retrieves the value of the environment variable +key+.
+  #
+  # Returns a frozen, deduplicated string. If the environment variable does not exist, returns nil.
+  #
+  # @param key [String] The environment variable name
+  # @return [String, nil] The frozen string value of the environment variable, or nil if not found
+  def self.[]: (String key) -> String?
+
+  # Retrieves the environment variable +key+.
+  #
+  # If the key exists, returns its frozen, deduplicated value.
+  # If the key does not exist:
+  # - With a block: yields the key to the block and returns the block's result
+  # - With a default argument: returns the default value
+  # - Without either: raises KeyError
+  #
+  # @param key [String] The environment variable name
+  # @return [String] The environment variable value
+  # @raise [KeyError] If the key is not found and no default or block is provided
+  def self.fetch: (String key) -> String
+                | [T] (String key, T default) -> (String | T)
+                | [T] (String key) { (String) -> T } -> (String | T)
+
+  # Returns true if the environment variable +key+ exists, false otherwise.
+  #
+  # @param key [String] The environment variable name
+  # @return [bool] true if the key exists, false otherwise
+  def self.key?: (String key) -> bool
+
+  # Alias for key?
+  alias self.has_key? self.key?
+
+  # Alias for key?
+  alias self.include? self.key?
+
+  # Alias for key?
+  alias self.member? self.key?
+
+  # Iterates over all environment variables.
+  #
+  # When called with a block, yields each environment variable as a [key, value]
+  # pair where both key and value are frozen, deduplicated strings. Returns Arctic.
+  #
+  # When called without a block, returns an Enumerator.
+  #
+  # @return [Arctic, Enumerator] Arctic module (when block given) or Enumerator (when no block)
+  # @yield [key, value] Gives each environment variable name and value
+  def self.each: () { (String key, String value) -> void } -> self
+               | () -> Enumerator[[String, String], self]
+
+  # Alias for each
+  #
+  # @return [Arctic, Enumerator] Arctic module (when block given) or Enumerator (when no block)
+  # @yield [key, value] Gives each environment variable name and value
+  def self.each_pair: () { (String key, String value) -> void } -> self
+                    | () -> Enumerator[[String, String], self]
+
+  # Returns an array containing all environment variable names.
+  #
+  # Each key is a frozen, deduplicated string for memory efficiency.
+  #
+  # @return [Array<String>] An Array of frozen String keys
+  def self.keys: () -> Array[String]
+
+  # Returns an array containing all environment variable values.
+  #
+  # Each value is a frozen, deduplicated string for memory efficiency.
+  #
+  # @return [Array<String>] An Array of frozen String values
+  def self.values: () -> Array[String]
+
+  # Returns a Hash containing all environment variables.
+  #
+  # Both keys and values are frozen, deduplicated strings for memory efficiency.
+  #
+  # @return [Hash<String, String>] A Hash mapping environment variable names to their values
+  def self.to_h: () -> Hash[String, String]
+
+  # Alias for to_h
+  #
+  # @return [Hash<String, String>] A Hash mapping environment variable names to their values
+  alias self.to_hash self.to_h
+
+  # Returns true if the environment contains no variables, false otherwise.
+  #
+  # @return [bool] true if environment is empty, false otherwise
+  def self.empty?: () -> bool
+
+  # Returns the number of environment variables.
+  #
+  # @return [Integer] The count of environment variables
+  def self.size: () -> Integer
+
+  # Alias for size
+  alias self.length self.size
+
+  # Returns a string representation of the Arctic module.
+  #
+  # @return [String] A String containing the inspection representation
+  def self.inspect: () -> String
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: arctic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Persona
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-22 00:00:00.000000000 Z
+dependencies: []
+description: Arctic provides an ENV-like interface that returns frozen, deduplicated
+  strings to reduce memory allocations. Implemented as a C extension using Ruby's
+  fstring table.
+email:
+- rubygems@withpersona.com
+executables: []
+extensions:
+- ext/arctic/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/arctic/arctic.c
+- ext/arctic/extconf.rb
+- lib/arctic.rb
+- sig/arctic.rbs
+homepage: https://github.com/persona-id/arctic
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/persona-id/arctic
+  source_code_uri: https://github.com/persona-id/arctic
+  changelog_uri: https://github.com/persona-id/arctic/blob/main/CHANGELOG.md
+  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: '3.3'
+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: Frozen, deduplicated environment variable access
+test_files: []