philiprehberger-safe_yaml

Safe YAML loading with restricted types, schema validation, and size limits

Requirements

• Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-safe_yaml"

Or install directly:

gem install philiprehberger-safe_yaml

Usage

require "philiprehberger/safe_yaml"

# Load a YAML string safely
data = Philiprehberger::SafeYaml.load("name: Alice\nage: 30\n")
# => {"name"=>"Alice", "age"=>30}

# Load from a file
data = Philiprehberger::SafeYaml.load_file("config.yml")

Size Limits

# Reject oversized input
Philiprehberger::SafeYaml.load(huge_string, max_size: 1024)
# => raises Philiprehberger::SafeYaml::SizeError if input exceeds 1024 bytes

Permitted Classes

# Allow specific classes during deserialization
data = Philiprehberger::SafeYaml.load(yaml_string, permitted_classes: [Symbol, Date])

Safe Serialization

require "philiprehberger/safe_yaml"

data = { "host" => "localhost", "port" => 3000, "debug" => true }
yaml_string = Philiprehberger::SafeYaml.dump(data)
Philiprehberger::SafeYaml.dump_file(data, "config.yml")

Schema Validation

schema = Philiprehberger::SafeYaml::Schema.new do
  required :name, String
  required :age, Integer
  optional :email, String
end

data = Philiprehberger::SafeYaml.load("name: Alice\nage: 30\n")

# Validate with exceptions
schema.validate!(data)
# => true (or raises SchemaError)

# Validate without exceptions
result = schema.validate(data)
# => { valid: true, errors: [] }

Alias Limits

# Block all aliases (default behavior)
Philiprehberger::SafeYaml.load(yaml_with_aliases)
# => raises Psych::BadAlias

# Allow up to 3 aliases
data = Philiprehberger::SafeYaml.load(yaml_with_aliases, max_aliases: 3)

# Exceeding the limit raises an error
Philiprehberger::SafeYaml.load(yaml_with_many_aliases, max_aliases: 2)
# => raises Philiprehberger::SafeYaml::Error

Load and Validate

schema = Philiprehberger::SafeYaml::Schema.new do
  required :name, String
  required :port, Integer
end

# Parse and validate in one step
data = Philiprehberger::SafeYaml.load_and_validate("name: app\nport: 3000\n", schema: schema)
# => {"name"=>"app", "port"=>3000}

# Raises SchemaError if validation fails
Philiprehberger::SafeYaml.load_and_validate("name: app\n", schema: schema)
# => raises Philiprehberger::SafeYaml::SchemaError

Sanitize

raw = "# This is a comment\nname: Alice\n# Another comment\nage: 30\n"
cleaned = Philiprehberger::SafeYaml.sanitize(raw)
# => "name: Alice\nage: 30\n"

Defaults Merge

defaults = { 'host' => 'localhost', 'port' => 3000, 'db' => { 'pool' => 5, 'timeout' => 30 } }
yaml = "port: 8080\ndb:\n  pool: 10\n"

data = Philiprehberger::SafeYaml.load_with_defaults(yaml, defaults: defaults)
# => {"host"=>"localhost", "port"=>8080, "db"=>{"pool"=>10, "timeout"=>30}}

Custom Validation Rules

schema = Philiprehberger::SafeYaml::Schema.new do
  required :port, Integer, rule: ->(v) { (1..65_535).cover?(v) }, message: 'must be between 1 and 65535'
  required :status, String, rule: ->(v) { %w[active inactive].include?(v) }
  optional :email, String, rule: ->(v) { v.include?('@') }, message: 'must be a valid email'
end

schema.validate!({ 'port' => 80, 'status' => 'active' })
# => true

result = schema.validate({ 'port' => 0, 'status' => 'unknown' })
# => { valid: false, errors: ["key port: must be between 1 and 65535", "key status: failed validation rule"] }

API

Method / Class	Description
SafeYaml.load(string, **opts)	Safely load a YAML string
SafeYaml.load_file(path, **opts)	Safely load a YAML file
SafeYaml.load_and_validate(string, schema:, **opts)	Load and validate in one step
SafeYaml.load_with_defaults(string, defaults:, **opts)	Load and deep merge over defaults
SafeYaml.sanitize(string)	Strip comments and normalize whitespace
SafeYaml.dump(data, permitted_classes:)	Safely dump data to a YAML string
SafeYaml.dump_file(data, path, permitted_classes:)	Safely dump data to a YAML file
Loader.load(string, permitted_classes:, max_aliases:, max_size:)	Core safe loading with all options
Loader.load_file(path, **opts)	Read file and delegate to Loader.load
Loader.dump(data, permitted_classes:)	Dump data to YAML with type validation
Loader.dump_file(data, path, permitted_classes:)	Write validated YAML to file
Schema.new(&block)	Define a validation schema with DSL
Schema#required(key, type, rule:, message:)	Declare a required key with expected type and optional validation rule
Schema#optional(key, type, rule:, message:)	Declare an optional key with expected type and optional validation rule
Schema#validate!(data)	Validate and raise SchemaError on failure
Schema#validate(data)	Validate and return { valid:, errors: }
SafeYaml::Error	Base error class
SafeYaml::SchemaError	Raised on schema validation failure
SafeYaml::SizeError	Raised when input exceeds max_size

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT