winreg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbe8c4f07ef7324d292aacf40153e5f25e412fea50699cd344b066159c9fc48a
+  data.tar.gz: e9cc1596e5a598c6b3c1243dcafc2e504e95e96519053aec5888b04634a88cbf
+SHA512:
+  metadata.gz: b0c0714cd31ca0e62c9cfc141ffde6c9e67cc4f42e645f2787bbed9091aed99f58805dff6df0107eeca06dd6f316fce73662fa70b87a3e3b5347d61f8fdf8ba9
+  data.tar.gz: dfc6db4e5ab395ea033b5d691f6df7042e744083954c6bd0a717c04426e2daca3c5335e89c2b2d157502f6c6b0157617b52cf5914820d564cdd5a229b1864ba3

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [0.1.0] - 2026-06-01
+
+Initial release.
+
+- **Typed reads** — strict `string`/`dword`/`qword`/`multi_string`/`binary`
+  readers (and their `?` no-raise-on-missing variants) plus a generic
+  `read`/`read?` returning `[type, value]`. REG_SZ/REG_EXPAND_SZ decode to UTF-8
+  with at most one trailing NUL stripped (unterminated values round-trip);
+  REG_EXPAND_SZ is never auto-expanded; REG_MULTI_SZ decodes to `Array<String>`
+  tolerating missing/excess terminators; REG_DWORD/REG_QWORD are size-checked.
+- **Typed writes** — `write_string`, `write_expand_string`, `write_multi_string`
+  (correct double-NUL wire format), range-checked `write_dword`/`write_qword`,
+  `write_binary`, and the generic `write(name, type, value)`. Embedded NULs and
+  empty REG_MULTI_SZ elements are rejected, so the gem never produces a malformed
+  value.
+- **Raw escape hatches** — `raw`/`write_raw` move exact bytes under an arbitrary
+  type tag, never decoding, for forensic and adversarial data.
+- **Default value** — `nil`/`""` addresses the unnamed default value for every
+  read/write/delete/probe.
+- **WOW64 views** — `view: :v64`/`:v32` is a first-class constructor option,
+  stored on the `Key` and re-applied consistently to every child open/create,
+  `delete_key`, `key?` probe, and `Watch` handle; children cannot override it.
+- **Least-privilege opens** — `access: :read` is `KEY_READ`; writes demand an
+  explicit `access: :read_write`; `KEY_ALL_ACCESS` appears nowhere.
+- **Enumeration & metadata** — `each_value`/`each_key`/`value_names`/`key_names`
+  (16,383-char value names) and `info` (counts + 100ns-precision
+  `last_write_time`).
+- **Subkeys** — handle-relative `open`/`create` and `delete_key`
+  (`recursive: true` does a view-aware, interruptible, deepest-first walk).
+- **Change notification** — `Key#watch` returns a `Winreg::Watch` (or loops in
+  block form); `wait` returns `:changed`/`:deleted`/`nil`. Registrations are
+  `REG_NOTIFY_THREAD_AGNOSTIC` and rearmed before delivery (no final state is
+  ever missed); waits release the GVL and are interruptible standalone, and run
+  cooperatively under a fiber scheduler (winloop) via a worker-thread offload.
+- Error taxonomy under `Winreg::Error`: `OSError` (with `#code`) and its
+  `NotFound`/`AccessDenied`/`KeyDeleted` subclasses, plus `TypeMismatch`,
+  `MalformedValue`, and `Closed`.
+
+Pure C extension over advapi32 + kernel32 (`rb_raise`/longjmp-safe; every handle
+freed by a TypedData finalizer). Windows MSVC (mswin) Ruby only.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ned
+
+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,283 @@
+# winreg
+
+**Typed Windows registry access for Ruby — exact wire formats, least-privilege opens, WOW64 views as a first-class option, and change notification that cooperates with a fiber scheduler.**
+
+Ruby's bundled `win32/registry` is pure Ruby over Fiddle, and it has accumulated
+a decade of wire-format bugs: it writes REG_MULTI_SZ without the trailing empty
+string (a 22-byte image where 24 is correct), it `NoMethodError`s on
+`read(nil)`/`[nil]` for a key's default value, and it `.chop`s the last
+character off any string whose stored bytes are not NUL-terminated. Its
+enumeration name buffer is 514 chars, so a value name of 515+ (the registry
+allows 16,383) raises. And it does not bind `RegNotifyChangeKeyValue` at all, so
+there is no way to watch a key for changes.
+
+`winreg` is a thin MSVC C extension that gets the bytes right. It exposes the
+Win32 registry through a typed, hard-to-misuse API: strict typed readers and
+writers that own serialization (so the wire format is correct by construction),
+raw escape hatches for adversarial data, working default-value access,
+range-checked integers, full-length enumeration, `KEY_READ`-not-`KEY_ALL_ACCESS`
+defaults, 32/64-bit views applied consistently to child operations, and change
+watching.
+
+The watch surface releases the GVL and is interruptible standalone, and runs
+**cooperatively** under a fiber scheduler such as
+[winloop](https://rubygems.org/gems/winloop) by offloading the blocking wait to a
+worker thread — so a parked watcher never stalls the loop. Plain registry data
+operations are microsecond-scale local calls; they run inline and never park a
+fiber.
+
+## API summary
+
+| What | API |
+|---|---|
+| Open / create | `Winreg.open(path, access:, view:)`, `Winreg.create(path, access:, view:)`, `Key#open`, `Key#create` |
+| Typed read | `Key#string` `#dword` `#qword` `#multi_string` `#binary` (+ `?` variants), `#read`/`#read?` → `[type, value]` |
+| Typed write | `Key#write_string` `#write_expand_string` `#write_multi_string` `#write_dword` `#write_qword` `#write_binary`, `#write(name, type, value)`, `#delete_value` |
+| Raw escape hatch | `Key#raw` → `[tag, bytes]`, `Key#write_raw(name, tag, bytes)` |
+| Enumerate | `Key#each_value` `#each_key` `#value_names` `#key_names` |
+| Info | `Key#info` → counts + `last_write_time` |
+| Delete | `Key#delete_value`, `Key#delete_key(name, recursive:)` |
+| Probes | `Key#value?`, `Key#key?` |
+| Views | `view: :default | :v64 | :v32` (inherited by children) |
+| Watch | `Key#watch(subtree:, filter:)` → `Winreg::Watch`, `Watch#wait(timeout:)` |
+| Expand | `Winreg.expand_string(str)`, `Key#string(name, expand: true)` |
+
+## Requirements
+
+- **Windows 10 or newer** with a native **MSVC (mswin)** Ruby. Not supported on
+  MinGW/UCRT. (The change-notification path relies on
+  `REG_NOTIFY_THREAD_AGNOSTIC`, which is Windows 8+.)
+- Visual Studio 2017+ / Build Tools with the **Desktop development with C++** workload.
+- x64. arm64-mswin is expected to work (the code is arch-neutral) but is
+  untested and unsupported until an arm64-mswin Ruby distribution exists.
+
+## Install
+
+```sh
+gem install winreg
+```
+
+## Reading typed values
+
+No elevation is needed to read most of `HKLM\SOFTWARE`:
+
+```ruby
+require "winreg"
+
+Winreg.open('HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion') do |k|
+  k.string("ProductName")             # => "Windows 10 ..."
+  k.read("CurrentMajorVersionNumber") # => [:dword, 10]
+  k.string?("NoSuchValue")            # => nil  (the ? readers return nil when missing)
+end
+```
+
+`read` returns `[type, value]` where `type` is a Symbol from `Winreg::TYPES`
+(or the raw Integer tag for types outside the table). Strict typed readers
+(`string`, `dword`, …) raise `Winreg::TypeMismatch` if the stored type differs —
+a wrong type is a bug, not an absence, so even the `?` variants raise on a type
+mismatch (they only swallow "missing").
+
+## Writing
+
+Writers own serialization, so the wire format is correct by construction
+(double-NUL REG_MULTI_SZ, byte counts including terminators). They require a key
+opened `access: :read_write`:
+
+```ruby
+Winreg.create('HKCU\Software\Vendor\App') do |k|
+  k.write_string("InstallDir", 'C:\Vendor\App')
+  k.write_expand_string("Cache", '%LOCALAPPDATA%\Vendor')
+  k.write_multi_string("Plugins", %w[alpha beta])  # correct double-NUL wire format
+  k.write_dword("Port", 8080)
+
+  k.multi_string("Plugins")           # => ["alpha", "beta"]
+  k.dword("Port")                     # => 8080
+
+  k.write_dword("Port", -1)           # raises RangeError (stdlib silently wraps to 0xFFFFFFFF)
+  k.dword("InstallDir")               # raises Winreg::TypeMismatch (it is REG_SZ)
+end
+```
+
+Integers are unsigned and range-checked (`0..2**32-1` / `0..2**64-1`); embedded
+NULs in string data and empty/NUL-containing REG_MULTI_SZ elements are rejected
+with `ArgumentError` — the gem never produces a malformed value.
+
+## The default value
+
+The unnamed (default) value is addressed by `nil` or `""` for every operation —
+the case where the stdlib raises `NoMethodError`:
+
+```ruby
+Winreg.open('HKCU\Software\Classes\CLSID') do |k|
+  k.read?(nil)                        # => [:sz, "..."] or nil
+end
+```
+
+## Expand strings
+
+REG_EXPAND_SZ values are returned **literally** — the `%VAR%` text and the true
+`:expand_sz` type are preserved, never silently expanded or masked to `:sz`.
+Expansion is explicit and uses `ExpandEnvironmentStringsW` (not a Ruby gsub over
+`ENV`, whose semantics differ — unknown variables are left literal exactly as the
+OS defines):
+
+```ruby
+k.string("Cache")                     # => "%LOCALAPPDATA%\\Vendor"   (unexpanded)
+k.string("Cache", expand: true)       # => "C:\\Users\\me\\AppData\\Local\\Vendor"
+Winreg.expand_string('%TEMP%\\x')     # => "C:\\Users\\me\\AppData\\Local\\Temp\\x"
+```
+
+## Enumerating
+
+```ruby
+Winreg.open('HKCU\Software\Vendor\App') do |k|
+  k.each_value { |name, type, value| puts "#{name} (#{type}) = #{value.inspect}" }
+  k.value_names                       # => ["InstallDir", "Cache", "Plugins", "Port"]
+  k.key_names                         # => subkey names
+
+  info = k.info
+  info.value_count                    # => Integer
+  info.last_write_time                # => Time (100ns FILETIME precision)
+end
+```
+
+Enumeration is live and snapshot-less; kernel order is arbitrary and concurrent
+mutation may skip or repeat entries. `each_value` decodes data and so can raise
+`MalformedValue` on a hostile value mid-iteration — use `value_names` + `raw` for
+forensic robustness (it never decodes).
+
+## WOW64 views
+
+A 32/64-bit view is a constructor option, stored on the key and **automatically
+re-applied** to every child `open`/`create`, `delete_key`, `key?` probe, and
+`Watch`. Children cannot override it — this is the API encoding of the
+view-consistency rule, so you never accidentally cross the redirection boundary:
+
+```ruby
+Winreg.create('HKCU\Software\Classes\CLSID\{...}', view: :v64) do |k|
+  child = k.create("Sub")             # also :v64, no way to ask for :v32 here
+end
+```
+
+Avoid addressing `Wow6432Node` literally; use `view:` instead.
+
+## Watching for changes
+
+`Key#watch` returns an armed `Winreg::Watch`, or loops in block form. The block
+form yields `:changed` per coalesced change and yields `:deleted` once (then
+returns) when the watched key is deleted:
+
+```ruby
+Winreg.create('HKCU\Software\Vendor\App') do |k|
+  k.watch(filter: :values) do |event|
+    case event
+    when :changed then reload_config!
+    when :deleted then break
+    end
+  end
+end
+```
+
+The primitive form takes a timeout (seconds; `nil` = infinite):
+
+```ruby
+w = key.watch(subtree: true)
+case w.wait(timeout: 5)
+when :changed then puts "something under #{key.path} changed"
+when :deleted then puts "key is gone"
+when nil      then puts "no change in 5s"
+end
+w.close
+```
+
+`filter:` is a Symbol or Array of `:values`, `:keys`, `:attributes`, `:security`,
+`:default` (= keys + values), or `:all`. Notifications **coalesce** (`:changed`
+means "≥ 1 matching change since the previous delivery") and carry **no
+payload** — no value name, no change kind. The contract is "something changed; go
+look"; diff it yourself (e.g. compare `info.last_write_time` snapshots). The
+registration is rearmed *before* each delivery, so the final state is never
+missed; the cost is that one spurious wakeup is possible. The `Watch` opens its
+own private `KEY_NOTIFY` handle, so closing the originating `Key` does not disturb
+it.
+
+### Fiber schedulers (winloop)
+
+`Watch#wait` is the only blocking call. Under a live `Fiber.scheduler` such as
+[winloop](https://rubygems.org/gems/winloop) the native wait is offloaded to a
+worker thread and `Thread#value` parks the calling fiber through the scheduler's
+hooks, so the loop keeps serving other fibers:
+
+```ruby
+require "winloop"
+Winloop.run do
+  Fiber.schedule do
+    Winreg.create('HKCU\Software\Vendor\App') do |k|
+      k.watch(filter: :values) { |e| break if e == :deleted }
+    end
+  end
+  Fiber.schedule { do_other_io }
+end
+```
+
+With no scheduler the same call just blocks the calling thread (releasing the GVL,
+interruptible by `Thread#kill` / `Ctrl-C` / `Timeout`). Caveat: a fiber unwound
+between the worker observing `:changed` and value delivery loses that one
+delivery — harmless, because `:changed` is stateless and the registration stays
+armed, so the next change still fires.
+
+## Raw escape hatches
+
+`raw`/`write_raw` move exact bytes under an arbitrary type tag and never decode,
+for adversarial data or types outside the typed surface:
+
+```ruby
+tag, bytes = k.raw("Plugins")         # => [7, "a\x00l\x00...\x00\x00\x00\x00"]
+k.write_raw("Custom", 8, bytes)       # arbitrary type tag (REG_RESOURCE_LIST here)
+```
+
+## Errors
+
+```
+StandardError
+└─ Winreg::Error
+    ├─ Winreg::OSError          # a Windows API failed; #code is the LSTATUS / Win32 code
+    │   ├─ Winreg::NotFound       # ERROR_FILE_NOT_FOUND (2)
+    │   ├─ Winreg::AccessDenied   # ERROR_ACCESS_DENIED  (5)
+    │   └─ Winreg::KeyDeleted     # ERROR_KEY_DELETED    (1018): the handle is valid, the key is gone
+    ├─ Winreg::TypeMismatch     # a typed reader's stored type differs
+    ├─ Winreg::MalformedValue   # stored bytes don't decode as the claimed type
+    └─ Winreg::Closed           # an operation on a closed Key or Watch
+```
+
+Plain argument mistakes raise Ruby's own `ArgumentError` / `TypeError` /
+`RangeError` (e.g. an integer out of range) — those are misuse, not OS state.
+
+## Notes & limitations
+
+- **Notifications coalesce and carry no payload.** A single `:changed` may stand
+  for many changes; you get a symbol, not what changed. Diff it yourself.
+- **`RegRestoreKey` deletion is not detected.** A key replaced via
+  `RegRestoreKey` does not surface as `:deleted` (an OS limitation).
+- **Names with invalid UTF-16 are lenient-decoded.** Enumeration never aborts on
+  a hostile name; such names come back with U+FFFD replacement and therefore
+  cannot be round-trip addressed through the gem (a deliberate v1 trade — the
+  alternative makes a whole key unenumerable).
+- **Embedded NULs in stored string data are preserved**, not silently truncated
+  to the Win32-consumer view (`"a\0b"` reads as `"a\0b"`); writers reject embedded
+  NULs so the gem never creates such a value.
+- **Forward slash is a legal key-name character.** The path parser splits on
+  backslash only and never translates `/`.
+- **Keep values ≤ ~2 KiB** per Microsoft guidance (not enforced; the only hard
+  limit is the 4 GiB DWORD byte-count guard).
+- **HKLM writes need elevation.** 64-bit processes are never virtualized, so a
+  non-elevated HKLM write surfaces as an honest `Winreg::AccessDenied`.
+- **Remote registry is unsupported.** A path starting with `\\server\…` raises
+  `ArgumentError` at parse time.
+- Every kernel handle lives in a wrapper whose finalizer closes it, so a
+  forgotten `#close` never leaks — but closing explicitly (or using the block
+  forms) is good manners.
+- **Windows/MSVC only.** Links `advapi32` + `kernel32`, built with `cl.exe`.
+
+## License
+
+[MIT](LICENSE.txt).

data/ext/winreg/extconf.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the winreg extension — typed Windows registry access and
+# change notification (RegNotifyChangeKeyValue).
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    winreg requires a native Windows MSVC (mswin) Ruby — it binds the Win32
+    registry (RegOpenKeyExW/RegSetValueExW/RegNotifyChangeKeyValue) and is
+    built with cl.exe. Your Ruby is "#{RbConfig::CONFIG['arch']}".
+  MSG
+end
+
+# System import libs (bare "NAME.lib" tokens on mswin):
+#   advapi32 - registry APIs (RegOpenKeyExW/RegQueryValueExW/RegSetValueExW/
+#              RegEnumValueW/RegEnumKeyExW/RegQueryInfoKeyW/RegDeleteKeyExW/
+#              RegDeleteValueW/RegNotifyChangeKeyValue)
+# kernel32 (events, WaitForMultipleObjects, ExpandEnvironmentStringsW) is
+# linked by default. Pure C — no -EHsc, so rb_raise/longjmp is the normal,
+# safe error mechanism.
+$libs = [$libs, "advapi32.lib"].join(" ")
+
+create_makefile("winreg/winreg")