kanon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b9d154f9d3f8b311fe5b617c77b52aec339b2a61c906f788fcadb430f457749
+  data.tar.gz: 898efbcb49ce65f1b80c0e58b0b0ddcdbfd1c9946285272e153452611b757116
+SHA512:
+  metadata.gz: db7a72555e10af6a7ab0ca3568e5044b2fc291bdb6767865c61afd8eba87d42b04d10afdfead728a44971bc8bcfcd60acd8a768e0400fcfaa9d093f3ce32d335
+  data.tar.gz: 5949ad82bef351c5025a90ee6f25ef5eaa023f5277faac5f3a812f55040e6ff0278728af1bb4cf2050f3cb781465c79415447ee704e878dcffaf8fab002f6cd3

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0
+
+- A YAML file becomes a deeply frozen tree of nodes, read once per process, with
+  dotted access, `[]`, `dig`, `key?`, `keys` and `to_h`.
+- A file is read through the section named after the current environment, and read
+  whole when it carries no such section. A single root key leaves the data only
+  when it holds a hash of its own.
+- Values that belong to the environment are declared in the same file. A name
+  derives from the path, an array index joining it as a segment of its own; `env`
+  writes the name out instead, `default` gives a fallback.
+- A value is mandatory unless it carries a `default` or `optional: true`. A read
+  that misses one stops the application, naming every absent variable at once. An
+  empty variable counts as absent.
+- `type` casts to `string`, `integer`, `float`, `boolean` or `list`; without it
+  the class of the default decides, and a `type` written and left empty is refused
+  rather than ignored. Integers are read as decimal, so a leading zero is not
+  octal.
+- A typo in a key raises `NoMethodError` listing the available keys, never a
+  silent `nil`.
+- `expected_variables` reports the names a file reads and whether each is
+  mandatory. It walks the file the way a read does with nothing behind it, so it
+  refuses a file that could not load instead of reporting a clean list.
+- Everything the loader raises descends from `Kanon::Error`, including a name no
+  shell could set, two paths reading one variable, two keys that differ only by
+  quoting, a file that cannot be opened, and a directory or environment set to
+  nothing.
+- Inspection, serialization and error messages carry key names, classes and
+  lengths — never values. `Marshal.dump` refuses, and a wrapped failure drops the
+  exception that caused it, so the text that broke a cast or a template tag cannot
+  reach a log.
+- ERB runs before YAML is parsed. Parsing goes through `safe_load` on every psych
+  version.
+- The format is specified in `docs/specification.md` without reference to Ruby,
+  and the reasons behind it are in `docs/decisions.md`.
+- Ruby 2.7 and newer. Nothing outside the standard library.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksimenko Pavel
+
+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,295 @@
+# Kanon
+
+[![CI](https://github.com/MaksimenkoPG/kanon/actions/workflows/ci.yml/badge.svg)](https://github.com/MaksimenkoPG/kanon/actions/workflows/ci.yml)
+
+One way to read application configuration: a YAML file becomes a frozen tree of
+nodes, and the values that belong to the environment are declared in that same
+file.
+
+```ruby
+Kanon[:service].token
+```
+
+## What it is for
+
+Reading configuration tends to accumulate: a framework helper in one place,
+`YAML.load` with ERB in another, `YAML.load_file` inside a class in a third. None
+of them caches, so global constants appear for the sole purpose of reading a file
+once. Access forms multiply, and a typo returns `nil` — which is how a credential
+is silently dropped and an application boots into an outage.
+
+So the defaults here are the opposite ones:
+
+- **A value is mandatory unless declared otherwise.** A missing one brings the
+  application down at boot, naming every absent variable at once.
+- **A typo raises.** `NoMethodError` with the available keys in the message,
+  never a silent `nil`.
+- **What was read cannot change.** The tree is deeply frozen and read once per
+  process.
+- **The file states which variables exist.** That list can be extracted without
+  reading the environment, so a pre-boot check needs no grammar of its own.
+- **A secret never leaves through diagnostics.** Inspection, serialization and
+  error messages carry key names, classes and lengths — never values.
+
+## Installation
+
+```ruby
+gem 'kanon'
+```
+
+Ruby 2.7 or newer. Nothing outside the standard library: `yaml`, `erb`, `monitor`,
+and `json` when `to_json` is called.
+
+## A configuration file
+
+```yaml
+default: &default
+  :service:
+    :endpoint: "https://service.example.com"
+    :token: ~
+    :timeout: { default: 5 }
+    :recipients: { type: list, default: [ops@example.com] }
+    :verbose: { default: false }
+
+production:
+  <<: *default
+```
+
+The variables it expects:
+
+```sh
+SERVICE_TOKEN=a-real-token
+SERVICE_RECIPIENTS=alice@example.com,bob@example.com
+```
+
+What the application gets:
+
+```ruby
+Kanon[:service].token        # => "a-real-token"
+Kanon[:service].recipients   # => ["alice@example.com", "bob@example.com"]
+Kanon[:service].timeout      # => 5
+Kanon[:service].verbose      # => false
+```
+
+**Which part of the file is read.** A file is read through the section named after
+the current environment; one whose top level carries no such key is read whole, so
+a list or a dictionary needs no section wrapper around it. A single root key
+becomes the prefix of every variable name below it, and leaves the data when what
+it holds is a hash of its own — hence `Kanon[:service].token` above, not
+`.service.token`. Over a list or over a declaration it stays in the data and only
+lends its name, and several root keys all stay, each prefixing its own subtree.
+
+**What a scalar means.** A scalar holding a value is a constant of the file and
+never looks at the environment. An empty one means "expected and not given", under
+a name built from the path with levels joined by a single `_`: `service` → `token`
+reads `SERVICE_TOKEN`, and a nested `pool` → `size` would read
+`SERVICE_POOL_SIZE`.
+
+**What a hash means.** A hash whose keys all come from the four words below
+declares a value the environment may provide, so `timeout` stays `5` until
+`SERVICE_TIMEOUT` says otherwise.
+
+- **`env`** — the variable name, written out instead of derived from the path.
+- **`default`** — the value when the variable is absent, cast the same way a
+  variable is.
+- **`type`** — one of `string`, `integer`, `float`, `boolean`, `list`. Writing the
+  key and leaving it empty is refused rather than ignored; leaving it out lets the
+  class of the `default` decide.
+- **`optional: true`** — the only way to let a value be missing and still boot.
+  Only a literal `true` counts: the string `'false'` is truthy in Ruby and would
+  otherwise switch the flag on. An empty string written as the `default` is a
+  different thing — it is a value, and it reaches the consumer.
+
+**Two forms whose sides look different.** A list is a real array in the file and
+one comma separated string in the environment, spaces around the commas ignored;
+an array default implies `type: list`. A variable that leaves no items after
+parsing, `,,` for instance, counts as no value at all and fails the boot rather
+than falling back to the default. A boolean takes `1`, `true`, `yes`, `on` and
+`0`, `false`, `no`, `off` in any case, stopping the boot on anything else and
+naming what it does accept. Numbers and strings hold no such surprise —
+`SERVICE_TIMEOUT=10` yields the integer `10`, and a leading zero is not octal.
+
+An array written out in the file is a different thing entirely from `type: list`,
+and the next section is about it.
+
+**How the file is processed.** ERB runs before YAML is parsed, so
+`<%= ENV.fetch(...) %>` needs no marker, both styles mix in one file, and control
+tags (`<% if %> ... <% end %>`) may build the structure of the file itself. YAML is
+then parsed with `safe_load` on every psych version: symbol keys and `<<: *default`
+anchors work, while `!ruby/...` tags and types outside the allowed list are never
+built.
+
+### Arrays
+
+An index is a path segment like any other key, so a value inside an array is
+named after the position it sits at:
+
+```yaml
+:service:
+  :queues:
+    - :name: ~        # SERVICE_QUEUES_0_NAME
+    - :name: ~        # SERVICE_QUEUES_1_NAME
+  :matrix:
+    - [~, ~]          # SERVICE_MATRIX_0_0, SERVICE_MATRIX_0_1
+```
+
+Depth is not limited; one segment joins the name per level. A file whose root is
+an array has no root key to borrow, so it takes the name of the file — the same
+name that wraps it into a node:
+
+```yaml
+# endpoints.yml
+- :url: ~             # ENDPOINTS_0_URL, read back as .endpoints[0].url
+```
+
+The position is the entire name, which makes these names brittle. Insert an
+element at the head and every name below it shifts by one: the value meant for one
+element lands in its neighbour, and the boot stops only if some name in the
+shifted range holds nothing. Reordering a list becomes an edit of the environment,
+not of the file alone.
+
+So an array the environment fills is usually better declared than written out.
+`type: list` gives the whole list one stable name, and `env` gives a single
+element a name of its own:
+
+```yaml
+:service:
+  :queues:
+    - :name: { env: PRIMARY_QUEUE }
+    - :name: { env: BACKUP_QUEUE }
+```
+
+An array whose values are all in the file asks nothing of the environment and
+carries none of this.
+
+## The interface
+
+- **`Kanon.directory`, `Kanon.environment`** — what is in force right now.
+- **`Kanon.directory = path`** — where the files live, `config` until set.
+- **`Kanon.environment = name`** — which section to read, taken from `APP_ENV`,
+  then `RAILS_ENV`, then `RACK_ENV`, else `development`; an empty variable is
+  skipped in favour of the next one, and surrounding whitespace is trimmed off
+  whichever name wins. Setting either of the two empties the cache.
+- **`Kanon[:service]`** — the node from the cache, the same object every time. On
+  a miss it falls back to `load_config`, so a cleared cache heals itself.
+- **`Kanon.load_config(:service)`** — reads once and remembers; later calls return
+  that same object.
+- **`Kanon.load_configs(:service, :storage)`** — the same for several names at
+  once, returning `{ service: node, storage: node }`.
+- **`Kanon.read_config(:service)`** — reads the file again and leaves the cache
+  alone. A new object with equal data, so compare readings by value.
+- **`Kanon.expected_variables(:service)`** — the names the file reads and whether
+  each is mandatory, `{ 'SERVICE_POOL_SIZE' => false }`, without reading one of
+  them. It walks the file the way a read does, so a file that could not load is
+  refused here too instead of reporting a clean list.
+- **`Kanon.loaded_files`** — which files the cache holds.
+
+Every reader that resolves values stops the application when a mandatory one is
+missing, naming every absent variable at once; `expected_variables` reads none of
+those variables and never fails that way — what it refuses is a file the loader
+could not read at all. One `load_configs` at boot turns this into a single check at
+startup instead of a failure at first use.
+
+A reader hands back a node, never a hash:
+
+- **`node.token`** — a key written out in the code. A typo raises `NoMethodError`
+  listing the keys that are there.
+- **`node[:token]`, `node['token']`** — a key computed at runtime, as a symbol or
+  a string.
+- **`node.dig(:pool, :size)`** — the same at depth, and into arrays by index.
+- **`node.key?(:token)`, `node.keys`** — what the node holds.
+- **`node.to_h`** — a copy for a third party that needs a hash. Its containers are
+  new and unfrozen; leaf strings stay the frozen ones of the tree.
+
+What any implementation of this format must do — the grammar of a declaration, how
+a variable name is derived, the casting table, the order of checks — is in
+[docs/specification.md](docs/specification.md). Why it is shaped that way, and the
+known edges it leaves, are in [docs/decisions.md](docs/decisions.md).
+
+## What the loader refuses
+
+Every name below lives under `Kanon::` and descends from `Kanon::Error`.
+
+- **`FileMissing`** — the file is absent, or the name is not a bare file name at
+  all.
+- **`InvalidSource`** — the file exists but cannot be read: a directory or a file
+  the process may not open, broken YAML, an alias with no anchor, a failing ERB
+  tag, a forbidden YAML type, a document that refers to itself through an alias,
+  or two keys that become one when they turn into symbols.
+- **`EmptyDirectory`** — the directory was set to nothing: `nil`, or a string with
+  no more than whitespace in it.
+- **`EmptyEnvironment`** — the environment was set to nothing, by the same
+  measure.
+- **`MissingValue`** — a mandatory value is absent or empty, naming every such
+  variable at once.
+- **`InvalidValue`** — a value does not fit its type, or a declaration names a
+  type outside the five.
+- **`InvalidDeclaration`** — a declaration carries an unsupported key.
+- **`InvalidVariableName`** — a name no shell could set, derived or written out
+  in `env`: anything but a letter or `_` followed by letters, digits and `_`.
+- **`ConflictingVariable`** — two paths read one variable, derived or explicit.
+- **`UnknownKey`** — an unknown key in `[]`, a `dig` that ran into a scalar, an
+  index past the end of an array.
+- **`ReservedKey`** — a key named after a node method, which would otherwise
+  shadow the value.
+
+Outside that family the loader lets Ruby speak: `NoMethodError` for a typo in a
+key, listing the keys that are there, and `FrozenError` for an attempt to change
+what was read.
+
+An empty string counts as an absent value. No message of Kanon's own prints a
+value: a failing cast reports the class and the length instead. Names it does
+print — a key, a variable, a declared type — so a secret an ERB tag put in one of
+those places reaches the message like any other name.
+
+Reserved keys are every public instance method the node has: its own (`[]`,
+`dig`, `key?`, `keys`, `to_h`, `==`, `eql?`, `hash`, `inspect`, `as_json`,
+`to_json`, `encode_with`, `marshal_dump`, `instance_variables`) and all of
+`Object`'s, `class` and `dup` and `send` and `freeze` and `tap` among them. Private
+`Kernel` methods such as `format` or `timeout` are free to be keys.
+
+## What never leaves through diagnostics
+
+`inspect`, `as_json`, `to_json` and `to_yaml` print key names only,
+`instance_variables` is empty and `Marshal.dump` refuses, so a tree of secrets
+reaches neither a JSON response, nor a log, nor a queue. A typo reports what is
+there without any value: `undefined method 'tokn' for #<Kanon::Node keys: url,
+username, token>`.
+
+A failure the library wraps drops the exception that caused it, so the offending
+text cannot reach a log through `cause`, through `full_message` or through an
+exception tracker that walks the chain. Ruby's own `FrozenError` is the exception
+to all of this: an attempt to change a leaf prints the value it refused to change,
+and nothing here can stop it.
+
+One hole cannot be closed from here: `Oj.dump` in `:object` mode reads instance
+variables through the C API, past any Ruby method, and prints the values. That
+holds for every object of an application, not only these; the cure is
+`Oj.default_options = { mode: :compat }` on the application side.
+
+## What it is not
+
+- **Not a validator.** There is casting and there is mandatoriness; format,
+  ranges and allowed values are out of scope.
+- **Not hot reload.** A config is read once per process; changing a value means
+  restarting.
+- **Not a secret store.** Values arrive from the environment; rotation and
+  permissions belong to the infrastructure.
+- **Not a way to express structures through the environment.** Nested structures
+  live in the file. A variable overrides a scalar, or a flat list of scalars
+  given as a comma separated string.
+
+One edge is worth knowing before converting a file: a hash of data whose keys all
+come from the declaration vocabulary is read as a declaration, and a key named
+`env` makes one on its own. The rest are in
+[docs/decisions.md](docs/decisions.md).
+
+Reading through a node costs about five times a plain hash read, and about seven
+times when every read goes through `Kanon[...]`. It shows only in loops of hundreds
+of thousands of reads — on a hot path take the node into a local variable once. The
+numbers come from `script/benchmark.rb`, which needs no framework:
+`ruby -Ilib script/benchmark.rb`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/docs/decisions.md

@@ -0,0 +1,176 @@
+# Kanon: decisions and their reasons
+
+Why the format and the library are shaped the way they are. What an
+implementation must do is in [specification.md](specification.md); this document
+never restates a rule, only the thinking behind it.
+
+## Principles
+
+Break any of these and the solution stops being itself.
+
+**1. Configuration is data, not code.** Composition, defaults and types live in
+the file. Changing a value never means changing the application, and the whole
+shape of a configuration is visible in one place.
+
+**2. One way to read, one shape of access.** A node always comes out. There is no
+second entry point handing out a raw mapping, and the node never pretends to be
+one — partial resemblance hides a forgotten conversion until it breaks somewhere
+else.
+
+**3. What was read cannot change.** Immutability is what makes "read once" safe to
+rely on: a tree that nobody can edit is the same tree wherever it is passed. The
+copy handed to a third party has left the configuration and lives by that party's
+rules.
+
+**4. Read once, on first use.** Laziness exists so that a configuration the
+application does not need cannot keep it from starting. Caching exists so that a
+crowd of global constants does not appear for the sole purpose of reading a file
+once.
+
+**5. Failure is loud and early.** A missing value brings the application down at
+boot naming every absent variable at once, not one per restart. A typo in a key
+is an error listing what is there. The silent empty value is what all of this
+exists to prevent: a credential quietly dropped is an outage that starts long
+before anyone reads a log.
+
+**6. The file states which variables exist.** The structure is the single source
+of truth about what must be provided, and that list can be extracted without
+reading any of it, so a check before boot needs no grammar of its own.
+
+**7. No value leaves through the library's own diagnostics.** Names do — of keys,
+of variables, of declared types — because a refusal nobody can act on is worse than
+one that names what to fix, and a name built by a template tag is printed like any
+other. What the host language says on its own is outside this: the error Ruby
+raises for an attempt to change an immutable leaf prints the value it refused to
+change, and nothing in the library can stop it.
+
+**8. No framework underneath.** The standard library only, with the directory and
+the environment injected from outside. Without that there is no library, only a
+piece of somebody's application.
+
+**9. A configuration class is optional.** It appears only where something has to
+be computed. Reading data takes no code at all.
+
+**10. Whatever was read becomes one shape.** The consumer cannot tell where a
+value came from.
+
+## Settled
+
+**YAML, at a cost that is worth naming.** Six complications in the specification
+exist only because the format is YAML: a second document after `---`, a
+self-referring alias, an alias with no anchor, a forbidden tagged type, two keys
+that differ only by a leading colon, and what a file built on `default: &default`
+does when it is read outside its sections. A simpler format would carry none of
+them.
+
+It is still the right base. The library is meant to read configuration files a
+project already has, with the smallest possible edit, and such files are built on
+`default: &default` anchors and carry template tags. A format without anchors turns
+adopting the library into rewriting every file it is meant to read. YAML also
+comes with the standard library, while every alternative costs a dependency and
+with it principle 8.
+
+**Domain dictionaries do not belong to this layer.** Lists of types, tax tables and
+similar data are the same on every installation and change together with the code.
+Principles 5 and 6 work against them: a variable name would be derived from a data
+key, an empty entry would read as a missing variable, and arbitrary key text would
+be normalised. Dropping the demand for a section made such a file readable; it did
+not make reading it a good idea.
+
+**Values come from the environment, and from nothing else.** A pluggable source —
+a setter in place of the single environment lookup — was weighed and left out.
+Secret stores are reached before the process starts, by tools that export what they
+fetched, or by the secret injection of container platforms, and their values arrive
+as ordinary variables. One deployment would justify the seam: one forbidden to put
+secrets into the process environment at all. Until such a deployment exists the
+seam is an abstraction with a single implementation, and adding it later breaks
+nothing — the setter is new surface, not changed surface.
+
+**A derived name has to be one a shell could set.** Nothing else can satisfy it,
+so a name outside `[A-Za-z_][A-Za-z0-9_]*` is refused at boot rather than asked
+for and never answered.
+
+**A marker for declarations was rejected.** The one way to close the edge below
+where data can look like a declaration is to demand a marker on every declaration.
+That makes the common case pay for the rare one, and every existing file pay for a
+collision most of them never hit.
+
+## The Ruby surface
+
+```ruby
+Kanon[:name]                       # node from the cache, load_config on a miss
+Kanon.read_config(:name)           # node, reads the file every time
+Kanon.load_config(:name)           # node, reads once and remembers
+Kanon.load_configs(:one, :two)     # { one: node, two: node }
+Kanon.expected_variables(:name)    # { name => mandatory? }, reads no such variable
+Kanon.directory                    # and Kanon.directory = path
+Kanon.environment                  # and Kanon.environment = name
+Kanon.loaded_files                 # diagnostics
+```
+
+`read` and `load` split "read" from "read and remember"; `[]` is the consumer's
+form, honest because everything is warmed up at boot.
+
+Contracts that are easy to lose in a rewrite:
+
+- `load_configs` returns a name-to-node mapping on purpose: a one-letter typo
+  (`load_configs` instead of `load_config`) then fails on the same line.
+- `read_config` returns a new object with equal data every time. Only
+  `load_config` guarantees identity, so compare configurations by value.
+- `expected_variables` walks the file through the same code a read walks. A walk
+  of its own would drift from the real one, and did.
+
+## Known edges
+
+Consequences of the rules, documented rather than fixed. A conforming
+implementation reproduces them.
+
+**A data key can be mistaken for an environment section.** Not demanding a section
+costs one silent case: a file whose top-level key happens to be `test` or
+`production` is truncated to that branch without a word. A file built around a
+`default: &default` anchor gives itself away instead, because every copy of the
+anchor resolves at once — the read stops either on the values those copies expect,
+named with the section in front (`DEFAULT_SERVICE_TOKEN` beside
+`TEST_SERVICE_TOKEN`), or on two paths reading one variable where a declaration
+carries an explicit `env`.
+
+**A hash of data can look like a declaration.** Real data uses the four vocabulary
+words too. Most such collisions announce themselves: a `type` outside the five
+names is refused, and a declaration that demands a value stops the boot naming a
+variable nobody meant to set. It passes quietly only when the declaration it
+imitates demands nothing — it carries a `default`, or it is `optional` — and the
+subtree is then replaced by that default or by nothing. One key from outside the
+vocabulary keeps a mapping as data, and that is the escape when converting a file —
+but not for a mapping carrying `env`, which is a declaration on that key alone.
+
+**A misspelt declaration key turns the declaration into data.** `{ dfault: 5 }`
+carries no word of the vocabulary, so it is data, reads back as data and expects
+nothing. "A typo raises" covers a key read out of the tree; nothing can tell a near
+miss from a dictionary that happens to be worded that way.
+
+**Only the first document of a file is read.** Everything past a `---` separator is
+dropped without a word.
+
+**The shape of the tree depends on how much data is in the file.** A single root
+key over a mapping of its own is dropped, so removing the last but one entry of a
+dictionary changes every reading path.
+
+**A value with a default hides a vanished variable.** The default takes over
+silently; the report of expected variables names it, but nothing compares that list
+against the example environment file.
+
+**An index is a position, not a name.** Inserting an element into a sequence
+renames everything below it. The file keeps parsing and the shifted names keep
+resolving, so the mistake surfaces as wrong values rather than as a failure. A name
+that must survive reordering is written out with `env`.
+
+**Whitespace counts differently on the two sides.** A variable holding only spaces
+is a value, while an environment name holding only spaces is refused. A name made of
+spaces can mean nothing, and a value made of spaces can; the asymmetry is deliberate
+and easy to trip over.
+
+**A value reaches the consumer verbatim.** A declaration is substituted after the
+document has been parsed, so a value cannot add keys, define anchors or overwrite a
+neighbour the way it could through a template tag. In exchange the parser no longer
+folds control characters: what the source holds arrives as it is, which matters for
+values that end up in mail headers or glued into a URL.