winlog 0.1.0

data/lib/winlog/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Winlog
+  VERSION = "0.1.0"
+end

data/lib/winlog.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "winlog/version"
+require "winlog/winlog" # native extension: Winlog::Provider + Error/Closed + new_activity_id
+require "digest"
+
+# winlog — structured, registration-free ETW TraceLogging telemetry for Ruby:
+# events that cost nothing when nobody is listening.
+#
+# Register a provider by name (auto name-hashed GUID — no manifest, no message
+# DLL, no registry write, no elevation) and emit runtime-dynamic, self-describing
+# events decodable by WPA, PerfView, and the inbox logman/tracerpt with zero
+# setup. When no ETW session has enabled the provider, a `log` call is gated in
+# C before the fields are even looked at (~one Ruby method call). Emit-only:
+# events go to ETW sessions, NOT to Event Viewer.
+#
+#   PROV = Winlog.open("MyCompany.MyApp")
+#   PROV.log(:info, "Startup", version: "1.4.2", pid: Process.pid)  # => false (no session)
+#   Winlog.open("Tool") { |p| p.log(:info, "Ran", args: ARGV.join(" ")) }
+module Winlog
+  # Symbolic levels -> winmeta values (tracelogging.md §5, verified table).
+  LEVELS = {
+    critical: 1,   # WINEVENT_LEVEL_CRITICAL
+    error:    2,   # WINEVENT_LEVEL_ERROR
+    warn:     3,   # WINEVENT_LEVEL_WARNING
+    info:     4,   # WINEVENT_LEVEL_INFO
+    debug:    5,   # WINEVENT_LEVEL_VERBOSE
+    verbose:  5    # alias of :debug
+  }.freeze
+
+  # Symbolic opcodes -> winmeta values. START/STOP bracket activities.
+  OPCODES = { info: 0, start: 1, stop: 2 }.freeze
+
+  # Keyword bits 48..63 are reserved by Microsoft; winlog REJECTS them.
+  KEYWORD_RESERVED_MASK = 0xFFFF_0000_0000_0000
+
+  # 16 signature bytes prepended to the name before SHA-1, per the documented
+  # ETW name-hash algorithm (tracelogging.md §4).
+  GUID_SIGNATURE = [0x48, 0x2C, 0x2D, 0xB2, 0xC3, 0x90, 0x47, 0xC8,
+                    0x87, 0xF8, 0x1A, 0x15, 0xBF, 0xC1, 0x30, 0xFB].freeze
+  private_constant :GUID_SIGNATURE
+
+  # Printable ASCII (bytes 0x21..0x7E): no spaces, no control chars, no NUL.
+  NAME_PATTERN = /\A[\x21-\x7E]{1,255}\z/
+  private_constant :NAME_PATTERN
+
+  # Base class for everything winlog raises itself. (Error and Closed are
+  # actually defined in C so they exist before this file's reopen; documented
+  # here for the reader.)
+  #
+  #   class Winlog::Error  < StandardError; end
+  #   class Winlog::Closed < Winlog::Error; end
+
+  module_function
+
+  # Register a TraceLogging provider under +name+ and return a Winlog::Provider.
+  # Block form yields the provider and ensure-closes it, returning the block
+  # value. Registration is system-wide registration-FREE (no manifest, registry,
+  # or elevation). On a rare EventRegister failure NO exception is raised — the
+  # provider is a benign no-op; check #registered? (MS guidance).
+  #
+  #   Winlog.open("X")                     # => #<Winlog::Provider X {guid}>
+  #   Winlog.open("X") { |p| p.log(...) }  # => block value; provider closed after
+  def open(name)
+    prov = Provider.new(name)
+    return prov unless block_given?
+
+    begin
+      yield prov
+    ensure
+      prov.close
+    end
+  end
+
+  # The ETW name-hashed GUID for +name+ WITHOUT registering anything. Pure Ruby
+  # (SHA-1 over the documented signature + UTF-16BE upcased name, .NET byte
+  # order). Same +name+ rules as Winlog.open. Case-insensitive.
+  #
+  #   Winlog.guid_for("MyCompany.MyComponent")
+  #   # => "ce5fa4ea-ab00-5402-8b76-9f76ac858fb5"
+  def guid_for(name)
+    name = validate_name!(name)
+    bytes = Digest::SHA1.digest(
+      GUID_SIGNATURE.pack("C*") + name.upcase.encode("UTF-16BE").b
+    ).bytes[0, 16]
+    bytes[7] = (bytes[7] & 0x0F) | 0x50
+    [bytes[0, 4].reverse, bytes[4, 2].reverse, bytes[6, 2].reverse,
+     bytes[8, 2], bytes[10, 6]]
+      .map { |part| part.map { |b| format("%02x", b) }.join }
+      .join("-")
+  end
+
+  # Map a level (Symbol in LEVELS or Integer 1..255) to its winmeta Integer.
+  # Raises ArgumentError on an unknown Symbol or out-of-range Integer.
+  def level_for(level)
+    case level
+    when Symbol
+      LEVELS.fetch(level) do
+        raise ArgumentError, "unknown level #{level.inspect} " \
+                             "(known: #{LEVELS.keys.inspect})"
+      end
+    when Integer
+      unless level.between?(1, 255)
+        raise ArgumentError, "level must be 1..255, got #{level.inspect}"
+      end
+      level
+    else
+      raise ArgumentError,
+            "level must be a Symbol or Integer, got #{level.inspect}"
+    end
+  end
+
+  # Map an opcode (Symbol in OPCODES or Integer 0..255) to its Integer value.
+  def opcode_for(opcode)
+    case opcode
+    when Symbol
+      OPCODES.fetch(opcode) do
+        raise ArgumentError, "unknown opcode #{opcode.inspect} " \
+                             "(known: #{OPCODES.keys.inspect})"
+      end
+    when Integer
+      unless opcode.between?(0, 255)
+        raise ArgumentError, "opcode must be 0..255, got #{opcode.inspect}"
+      end
+      opcode
+    else
+      raise ArgumentError,
+            "opcode must be a Symbol or Integer, got #{opcode.inspect}"
+    end
+  end
+
+  # Validate a provider name: printable ASCII (0x21..0x7E), 1..255 bytes.
+  # Returns the name as a String. Raises ArgumentError on anything else.
+  def validate_name!(name)
+    str = String(name)
+    # Compare raw bytes so a broken/foreign encoding can never make the regex
+    # match raise (it would on an invalid byte sequence); printable ASCII is a
+    # pure byte predicate. Reuse the same 0x21..0x7E, 1..255 contract as
+    # NAME_PATTERN, then return a clean UTF-8 String.
+    bytes = str.bytes
+    ok = bytes.length.between?(1, 255) && bytes.all? { |b| b >= 0x21 && b <= 0x7E }
+    unless ok
+      raise ArgumentError,
+            "name must be 1..255 printable-ASCII bytes (0x21..0x7E: no spaces, " \
+            "control chars, or NUL), got #{name.inspect}"
+    end
+    str.b.force_encoding(Encoding::UTF_8)
+  end
+  private_class_method :validate_name!
+
+  # Native (TypedData) provider class; the C side defines the bridges and the
+  # read-only methods. The Ruby layer here adds the validated, ergonomic API.
+  class Provider
+    # The provider name as given (frozen UTF-8 String). Stored at initialize and
+    # never read back from provider metadata (tld swaps in empty NullMetadata on
+    # a failed registration). Correct regardless of registration outcome.
+    def name
+      raise Winlog::Closed, "winlog: provider is closed" if closed?
+
+      @name
+    end
+
+    # Same contract as Winlog.open (no block form here; open delegates to new).
+    # Raises ArgumentError on a bad name; never raises on EventRegister failure
+    # (see #registered?).
+    def initialize(name)
+      @name = Winlog.send(:validate_name!, name).dup.freeze
+      _register(@name)
+    end
+
+    # Emit one TraceLogging event. THE call of the gem.
+    #
+    #   level  : Symbol in LEVELS, or Integer 1..255.
+    #   event  : event name (Symbol or String; valid UTF-8, non-empty, no NUL).
+    #   fields : keyword splat of field-name => value pairs, plus the reserved
+    #            control kwargs keyword:/opcode:/activity:/related: (extracted by
+    #            exact Symbol key; String keys with the same text stay fields).
+    #
+    # Returns true if enabled and written, false if skipped/dropped. Never
+    # raises on delivery problems (ETW is lossy by design). Raises Winlog::Closed
+    # after close. Field-value type errors raise only when the event is enabled
+    # (the deliberate E2 asymmetry; control args validate on every call).
+    def log(level, event, **fields)
+      # Map opcode symbol -> integer here (Ruby owns the OPCODES table) without
+      # disturbing the String-key escape hatch: only a :opcode Symbol key is a
+      # control arg, and only when its value is a Symbol does it need mapping.
+      if fields.key?(:opcode) && fields[:opcode].is_a?(Symbol)
+        fields = fields.dup
+        fields[:opcode] = Winlog.opcode_for(fields[:opcode])
+      end
+      _log(Winlog.level_for(level), event, fields)
+    end
+
+    # Is any ETW session listening (with the given level/keyword filter)?
+    # Reads in-process enable state — no system call. Raises Winlog::Closed
+    # after close.
+    #
+    #   level:   nil (default; "any level") | Symbol in LEVELS | Integer 1..255
+    #   keyword: Integer 0..0x0000_FFFF_FFFF_FFFF (reserved bits raise)
+    def enabled?(level: nil, keyword: 0)
+      lvl = level.nil? ? nil : Winlog.level_for(level)
+      _enabled(lvl, keyword)
+    end
+
+    # Never raises, even closed.
+    def inspect
+      if closed?
+        "#<Winlog::Provider (closed)>"
+      else
+        "#<Winlog::Provider #{@name} {#{guid}}>"
+      end
+    end
+
+    private :_register, :_log, :_write, :_enabled
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: winlog
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: |
+  winlog emits Windows ETW TraceLogging events from Ruby with no manifest, no
+  message DLL, no registry writes, and no elevation: register a provider by
+  name (standard ETW name-hashed GUID), then log runtime-dynamic events with
+  typed fields (UTF-8 text, binary, int64, double, boolean) plus levels,
+  keywords, opcodes, and explicit activity IDs for correlation. Events are
+  self-describing and decode in WPA, PerfView, and the inbox logman/tracerpt
+  with zero setup; when no session is listening, a log call is gated in native
+  code before field processing and costs about one Ruby method call. Built on
+  Microsoft's MIT-licensed TraceLoggingDynamic.h (vendored). Emit-only: events
+  go to ETW sessions, not the Windows Event Log. Windows MSVC (mswin) Ruby only.
+executables: []
+extensions:
+- ext/winlog/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/winlog/TraceLoggingDynamic.h
+- ext/winlog/extconf.rb
+- ext/winlog/winlog.cpp
+- lib/winlog.rb
+- lib/winlog/version.rb
+homepage: https://github.com/main-path/winlog
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/winlog
+  source_code_uri: https://github.com/main-path/winlog
+  changelog_uri: https://github.com/main-path/winlog/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/winlog/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Structured, registration-free ETW TraceLogging telemetry for Ruby — events
+  that cost nothing when nobody is listening.
+test_files: []