wintoast 0.1.0

data/lib/wintoast/payload.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Wintoast
+  # Wintoast::Payload — the ToastGeneric XML builder.
+  #
+  # A pure function with no OS calls: it turns a title/body plus presentation
+  # kwargs into the exact UTF-8 XML string that Wintoast.toast hands to the WinRT
+  # LoadXml call. Exposed publicly so you can inspect "what would you send?" and
+  # as the unit-test seam for the escaping / control-char / audio-table rules.
+  #
+  #   Wintoast::Payload.build("Build done", "42 files", audio: :mail)
+  #   # => "<toast>...<binding template=\"ToastGeneric\">...</toast>"
+  #
+  # It validates only the kwargs that affect the XML (attribution:, image:,
+  # hero:, circle:, audio:, duration:, scenario:). aumid:/tag:/group:/expires_*
+  # are WinRT properties, not part of the XML, and are NOT accepted here.
+  module Payload
+    module_function
+
+    # Accepted <audio> symbols -> the ms-winsoundevent token (without the
+    # "ms-winsoundevent:" prefix) and whether the sound loops. These are the
+    # ONLY sounds Windows honors for unpackaged apps; arbitrary file paths
+    # silently fall back to the default sound, so they are not accepted.
+    SHORT_SOUNDS = {
+      im:       "Notification.IM",
+      mail:     "Notification.Mail",
+      reminder: "Notification.Reminder",
+      sms:      "Notification.SMS"
+    }.freeze
+    private_constant :SHORT_SOUNDS
+
+    # Looping families: :alarm/:call plus :alarm2..:alarm10 / :call2..:call10.
+    # ms-winsoundevent uses "Looping.Alarm" (no 1) and "Looping.Alarm2".."10".
+    DURATIONS = %i[short long].freeze
+    private_constant :DURATIONS
+
+    SCENARIOS = {
+      alarm:         "alarm",
+      incoming_call: "incomingCall",
+      urgent:        "urgent"
+    }.freeze
+    private_constant :SCENARIOS
+
+    # Build the ToastGeneric XML. Returns a fresh, unfrozen UTF-8 String.
+    def build(title, body = nil,
+              attribution: nil,
+              image:       nil,
+              hero:        nil,
+              circle:      false,
+              audio:       :default,
+              duration:    :short,
+              scenario:    nil)
+      title_text = scrub_required(title, "title")
+      body_text  = body.nil?        ? nil : scrub_text(body, "body")
+      attr_text  = attribution.nil? ? nil : scrub_text(attribution, "attribution")
+
+      unless DURATIONS.include?(duration)
+        raise ArgumentError, "wintoast: duration: must be :short or :long, got #{duration.inspect}"
+      end
+      unless scenario.nil? || SCENARIOS.key?(scenario)
+        raise ArgumentError,
+              "wintoast: scenario: must be nil, :alarm, :incoming_call, or :urgent, got #{scenario.inspect}"
+      end
+
+      image_src = validate_image(image, "image")
+      hero_src  = validate_image(hero,  "hero")
+      if circle && image_src.nil?
+        raise ArgumentError, "wintoast: circle: true requires image:"
+      end
+
+      audio_xml = build_audio(audio)
+
+      toast_attrs = +""
+      toast_attrs << %( duration="long") if duration == :long
+      toast_attrs << %( scenario="#{SCENARIOS[scenario]}") if scenario
+
+      xml = +"<toast#{toast_attrs}>"
+      xml << "<visual><binding template=\"ToastGeneric\">"
+      xml << "<text>#{esc(title_text)}</text>"
+      xml << "<text>#{esc(body_text)}</text>" if body_text
+      xml << "<text placement=\"attribution\">#{esc(attr_text)}</text>" if attr_text
+      if image_src
+        crop = circle ? %( hint-crop="circle") : ""
+        xml << %(<image placement="appLogoOverride"#{crop} src="#{esc(image_src)}"/>)
+      end
+      if hero_src
+        xml << %(<image placement="hero" src="#{esc(hero_src)}"/>)
+      end
+      xml << "</binding></visual>"
+      xml << audio_xml if audio_xml
+      xml << "</toast>"
+      xml
+    end
+
+    # ---- validation / escaping helpers (module_function makes them callable) --
+
+    # Validate a String argument exists, normalize to UTF-8, and reject invalid
+    # UTF-8 BEFORE anything else (the §3.5 rule: never let bad bytes reach the C
+    # boundary — they would otherwise become a silently blank toast or a longjmp
+    # from the C conversion helper). Returns the UTF-8 String (control chars NOT
+    # yet scrubbed).
+    def normalize_utf8(value, label)
+      str = String.try_convert(value)
+      raise TypeError, "wintoast: #{label} must be a String, got #{value.class}" if str.nil?
+
+      str = str.encode(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8
+      unless str.valid_encoding?
+        raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
+      end
+      str
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      # A string tagged in another encoding that cannot transcode to UTF-8.
+      raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
+    end
+
+    # Strip the C0 control characters that XML 1.0 forbids even as references
+    # (everything < 0x20 except TAB/LF/CR). Returns a scrubbed UTF-8 String.
+    def scrub_text(value, label)
+      normalize_utf8(value, label).gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/, "")
+    end
+
+    # Like scrub_text but the result must be non-empty after scrubbing. A nil
+    # title is the "missing/empty" case (ArgumentError per §2.2), not a
+    # type error.
+    def scrub_required(value, label)
+      if value.nil?
+        raise ArgumentError, "wintoast: #{label} must be a non-empty string"
+      end
+
+      text = scrub_text(value, label)
+      if text.empty?
+        raise ArgumentError, "wintoast: #{label} must be a non-empty string"
+      end
+      text
+    end
+
+    # XML-escape the five metacharacters. Attribute positions are always
+    # double-quoted, so escaping " and ' covers both text and attribute use.
+    def esc(str)
+      str.gsub("&", "&amp;")
+         .gsub("<", "&lt;")
+         .gsub(">", "&gt;")
+         .gsub('"', "&quot;")
+         .gsub("'", "&apos;")
+    end
+
+    # Validate an image:/hero: path (nil passes through). Must be an absolute
+    # path to an existing regular file. Returns the scrubbed UTF-8 path or nil.
+    def validate_image(path, label)
+      return nil if path.nil?
+
+      str = normalize_utf8(path, label)
+      unless File.absolute_path?(str) && File.file?(str)
+        raise ArgumentError, "wintoast: #{label}: must be an absolute path to an existing file"
+      end
+      # Control chars are illegal in XML even in attributes; scrub for safety.
+      str.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/, "")
+    end
+
+    # Map audio: to an <audio> element string, or nil when the OS default is
+    # wanted (element omitted entirely).
+    def build_audio(audio)
+      case audio
+      when :default
+        nil
+      when false
+        %(<audio silent="true"/>)
+      when Symbol
+        if SHORT_SOUNDS.key?(audio)
+          %(<audio src="ms-winsoundevent:#{SHORT_SOUNDS[audio]}"/>)
+        elsif (token = looping_sound(audio))
+          %(<audio src="ms-winsoundevent:#{token}" loop="true"/>)
+        else
+          raise ArgumentError, "wintoast: unknown audio: #{audio.inspect}"
+        end
+      else
+        raise ArgumentError, "wintoast: unknown audio: #{audio.inspect}"
+      end
+    end
+
+    # :alarm / :alarm2..:alarm10 / :call / :call2..:call10 -> the Looping token,
+    # or nil if the symbol isn't a looping sound. :alarm1/:call1 and :alarm11+
+    # are rejected (Windows names them "Alarm" and "Alarm2".."Alarm10").
+    def looping_sound(sym)
+      m = /\A(alarm|call)([2-9]|10)?\z/.match(sym.to_s)
+      return nil unless m
+
+      base = m[1] == "alarm" ? "Alarm" : "Call"
+      "Notification.Looping.#{base}#{m[2]}"
+    end
+
+    private_class_method :normalize_utf8, :scrub_text, :scrub_required, :esc,
+                         :validate_image, :build_audio, :looping_sound
+  end
+end

data/lib/wintoast/version.rb

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

data/lib/wintoast.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "wintoast/version"
+require "wintoast/wintoast"  # native ext: defines _show/_register/_unregister/_progress + errors
+require "wintoast/payload"
+
+# wintoast — fire-and-forget Windows toast notifications and taskbar/terminal
+# progress, built on the inbox WinRT and shell APIs that already ship with
+# Windows. No Windows App SDK, no packaging, no COM activation server, no
+# elevation, nothing to install but the gem.
+#
+#   require "wintoast"
+#
+#   Wintoast.toast("Backup finished", "1,204 files in 38 s")   # => nil (a banner pops)
+#   Wintoast.progress(50)                                       # => true/false
+#   Wintoast.progress_clear                                     # => true/false
+#
+# A normal return from #toast means the OS ACCEPTED the toast — NOT that it was
+# displayed. Silent suppression (unregistered AUMID, Focus Assist, per-app
+# toggle, group policy) is undetectable by design of the platform; the gem never
+# pretends otherwise. See the README "The one trap you must know about".
+module Wintoast
+  # Misuse / non-OS failures (e.g. invalid UTF-8). OS API failures are OSError.
+  class Error < StandardError; end
+
+  # OS API failure. #code is an Integer: the HRESULT for COM/WinRT, or the Win32
+  # error code for registry calls. Attached in C via rb_iv_set(exc, "@code", ...).
+  class OSError < Error
+    def code = @code
+  end
+
+  # The AUMID of Windows PowerShell's Start-Menu shortcut — registered on every
+  # supported Windows box, so toasts sent with it always render (branded
+  # "Windows PowerShell"). The zero-setup default for Wintoast.toast.
+  POWERSHELL_AUMID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe"
+
+  module_function
+
+  # Fire-and-forget toast notification. Returns nil, always — a normal return
+  # means the OS accepted the toast, not that it was displayed (silent drops are
+  # undetectable). See §2.2 of the spec / the README for every kwarg.
+  #
+  # Raises ArgumentError / TypeError on bad arguments, Wintoast::Error on invalid
+  # UTF-8, and Wintoast::OSError (with #code = HRESULT) on a WinRT API failure.
+  def toast(title, body = nil,
+            aumid:       POWERSHELL_AUMID,
+            attribution: nil,
+            image:       nil,
+            hero:        nil,
+            circle:      false,
+            audio:       :default,
+            duration:    :short,
+            scenario:    nil,
+            expires_at:  nil,
+            expires_in:  nil,
+            tag:         nil,
+            group:       nil)
+    # Build the XML first: it validates title/body/attribution/image/hero/
+    # circle/audio/duration/scenario and normalizes + UTF-8-checks every text
+    # field, all in pure Ruby BEFORE any C bridge runs (the §3.5 regime).
+    xml = Payload.build(title, body,
+                        attribution: attribution, image: image, hero: hero,
+                        circle: circle, audio: audio, duration: duration,
+                        scenario: scenario)
+
+    aumid_u8 = validate_aumid_arg(aumid)
+    expire_ms = validate_expiry(expires_at, expires_in)
+    tag_u8   = validate_label(tag,   "tag")
+    group_u8 = validate_label(group, "group")
+
+    _show(aumid_u8, xml, expire_ms, tag_u8, group_u8)
+    nil
+  end
+
+  # Opt-in, reversible, per-user branding: writes ONLY
+  # HKCU\Software\Classes\AppUserModelId\<aumid> {DisplayName, IconUri?}.
+  # No elevation, no Start-Menu shortcut, no HKLM, no COM activator. Returns the
+  # aumid String. Raises ArgumentError on format violations, Wintoast::OSError
+  # (#code = Win32 error) on registry failures.
+  def register!(aumid:, display_name:, icon: nil)
+    aumid_u8 = validate_registry_aumid(aumid)
+
+    dn = String.try_convert(display_name)
+    raise TypeError, "wintoast: display_name: must be a String" if dn.nil?
+
+    dn = normalize_text(dn, "display_name")
+    raise ArgumentError, "wintoast: display_name: must be non-empty" if dn.empty?
+
+    icon_u8 =
+      if icon.nil?
+        nil
+      else
+        ic = normalize_text(icon, "icon")
+        unless File.absolute_path?(ic) && File.file?(ic)
+          raise ArgumentError, "wintoast: icon: must be an absolute path to an existing file"
+        end
+        ic
+      end
+
+    _register(aumid_u8, dn, icon_u8)
+    aumid_u8
+  end
+
+  # Delete the HKCU AppUserModelId key tree for the given aumid. Idempotent:
+  # returns false (no raise) when the key was not present. Only unregister AUMIDs
+  # YOU registered — deleting another app's HKCU key breaks its toasts.
+  def unregister!(aumid:)
+    _unregister(validate_registry_aumid(aumid))
+  end
+
+  # Drive taskbar + terminal progress. Returns true if at least one OS surface
+  # accepted the update, false if none did (no console at all, or a console whose
+  # taskbar leg also failed). Accepted != visible. Environmental failure is a
+  # false, never an exception — only argument misuse raises ArgumentError.
+  #
+  #   progress(50)                       determinate, green
+  #   progress(7, of: 23)                determinate from a ratio
+  #   progress(50, state: :error)        determinate, red
+  #   progress(50, state: :paused)       determinate, yellow
+  #   progress(state: :indeterminate)    marquee/ring (value must be nil)
+  #   progress(nil) / progress(:clear)   remove
+  def progress(value = nil, of: 100, state: nil)
+    unless of.is_a?(Numeric) && of.positive?
+      raise ArgumentError, "wintoast: of: must be a positive number, got #{of.inspect}"
+    end
+
+    # :indeterminate is value-less (the marquee ignores any percent). value must
+    # be nil; a supplied value (Numeric or :clear) is misuse. Checked first so
+    # progress(state: :indeterminate) is NOT mistaken for a clear.
+    if state == :indeterminate
+      unless value.nil?
+        raise ArgumentError, "wintoast: state: :indeterminate ignores value — pass value nil"
+      end
+      return _progress(3, 0)
+    end
+
+    # Clearing: value nil or :clear, and (because clear has no color) no state:.
+    if value.nil? || value == :clear
+      unless state.nil?
+        raise ArgumentError, "wintoast: clearing progress takes no state:, got #{state.inspect}"
+      end
+      return _progress(0, 0)
+    end
+
+    # Determinate: requires a Numeric value.
+    unless value.is_a?(Numeric)
+      raise ArgumentError, "wintoast: progress value must be a number, got #{value.inspect}"
+    end
+    state_int =
+      case state
+      when nil, :normal then 1
+      when :error       then 2
+      when :paused      then 4
+      else
+        raise ArgumentError, "wintoast: unknown state: #{state.inspect}"
+      end
+
+    _progress(state_int, pct(value, of))
+  end
+
+  # Remove progress. Equivalent to progress(nil).
+  def progress_clear = _progress(0, 0)
+
+  # ---- validation helpers (private) ----------------------------------------
+
+  # Normalize any String to UTF-8 and reject invalid UTF-8 in pure Ruby (§3.5).
+  def normalize_text(value, label)
+    str = String.try_convert(value)
+    raise TypeError, "wintoast: #{label} must be a String, got #{value.class}" if str.nil?
+
+    str = str.encode(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8
+    unless str.valid_encoding?
+      raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
+    end
+    str
+  rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+    raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
+  end
+
+  # aumid: for toast() — must be a non-empty String (StringValue semantics).
+  def validate_aumid_arg(aumid)
+    str = String.try_convert(aumid)
+    raise TypeError, "wintoast: aumid: must be a String, got #{aumid.class}" if str.nil?
+
+    str = normalize_text(str, "aumid")
+    raise ArgumentError, "wintoast: aumid: must not be empty" if str.empty?
+    str
+  end
+
+  # aumid: for register!/unregister! — the documented AUMID format: 1..128
+  # chars, no spaces, no control chars/NUL. Backslashes allowed (nested keys).
+  def validate_registry_aumid(aumid)
+    str = String.try_convert(aumid)
+    raise TypeError, "wintoast: aumid: must be a String, got #{aumid.class}" if str.nil?
+
+    str = normalize_text(str, "aumid")
+    if str.empty? || str.length > 128
+      raise ArgumentError, "wintoast: aumid: must be 1..128 characters, got #{str.length}"
+    end
+    if str.include?(" ")
+      raise ArgumentError, "wintoast: aumid: must not contain spaces"
+    end
+    if str.match?(/[\x00-\x1f]/)
+      raise ArgumentError, "wintoast: aumid: must not contain control characters"
+    end
+    str
+  end
+
+  # tag:/group: -> nil or a 1..64-char String. Empty or > 64 raises.
+  def validate_label(value, label)
+    return nil if value.nil?
+
+    str = String.try_convert(value)
+    raise TypeError, "wintoast: #{label}: must be a String, got #{value.class}" if str.nil?
+
+    str = normalize_text(str, label)
+    if str.empty? || str.length > 64
+      raise ArgumentError, "wintoast: #{label}: must be 1..64 characters, got #{str.length}"
+    end
+    str
+  end
+
+  # The epoch-ms whose WinRT DateTime tick — (ms + 11644473600000) * 10000, in
+  # 100-ns units since 1601 — still fits a signed int64. The C bridge performs
+  # exactly that multiply (wintoast.cpp), so any ms past this point would overflow
+  # int64 (undefined behavior) and hand the OS a garbage UniversalTime. The OS
+  # caps toast retention at 3 days anyway, so a far-future expiry is already
+  # meaningless; clamping here is observably correct and removes the UB window.
+  MAX_EXPIRE_MS = (2**63 - 1) / 10_000 - 11_644_473_600_000
+  private_constant :MAX_EXPIRE_MS
+
+  # expires_at:/expires_in: -> the absolute Unix epoch milliseconds, or nil.
+  # Mutually exclusive. expires_in must be a positive Numeric (seconds from now);
+  # expires_at must be a Time (past times pass through — the OS treats them as
+  # already expired; clocks skew, so we don't police it). The result is clamped
+  # to MAX_EXPIRE_MS so the C-side tick multiply can never overflow int64.
+  def validate_expiry(expires_at, expires_in)
+    if expires_at && expires_in
+      raise ArgumentError, "wintoast: pass only one of expires_at:/expires_in:"
+    end
+
+    if expires_in
+      unless expires_in.is_a?(Numeric) && expires_in.positive?
+        raise ArgumentError, "wintoast: expires_in: must be a positive number of seconds"
+      end
+      ms = ((Time.now.to_f + expires_in.to_f) * 1000.0).round
+      return ms.clamp(0, MAX_EXPIRE_MS)
+    end
+
+    if expires_at
+      unless expires_at.is_a?(Time)
+        raise ArgumentError, "wintoast: expires_at: must be a Time, got #{expires_at.class}"
+      end
+      ms = (expires_at.to_f * 1000.0).round
+      return ms.clamp(0, MAX_EXPIRE_MS)
+    end
+
+    nil
+  end
+
+  # Percent = round(value/of * 100), clamped 0..100. Overshoot is a routine
+  # rounding artifact in app loops, so it is clamped, not raised.
+  def pct(value, of)
+    ((value.to_f / of.to_f) * 100.0).round.clamp(0, 100)
+  end
+
+  private_class_method :_show, :_register, :_unregister, :_progress
+  private_class_method :normalize_text, :validate_aumid_arg, :validate_registry_aumid,
+                       :validate_label, :validate_expiry, :pct
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: wintoast
+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: |
+  wintoast pops native Windows toast notifications from plain Ruby scripts using
+  the WinRT notification API that ships with Windows — no Windows App SDK, no
+  packaging, no COM activation server, no elevation — and drives progress on the
+  taskbar button (ITaskbarList3) and the Windows Terminal tab (OSC 9;4) at the
+  same time, so progress shows up under classic conhost AND modern terminals.
+
+  API: Wintoast.toast (title/body/attribution, app logo + hero images, system
+  sounds, duration, scenario, expiration, tag/group), Wintoast.register! /
+  unregister! (opt-in, reversible, per-user HKCU AppUserModelId branding — no
+  shortcut, no admin), Wintoast.progress / progress_clear, and
+  Wintoast::Payload.build for inspecting the exact toast XML. Windows MSVC
+  (mswin) Ruby only.
+executables: []
+extensions:
+- ext/wintoast/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/wintoast/extconf.rb
+- ext/wintoast/wintoast.cpp
+- lib/wintoast.rb
+- lib/wintoast/payload.rb
+- lib/wintoast/version.rb
+homepage: https://github.com/main-path/wintoast
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/wintoast
+  source_code_uri: https://github.com/main-path/wintoast
+  changelog_uri: https://github.com/main-path/wintoast/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/wintoast/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: Fire-and-forget Windows toast notifications and taskbar/terminal progress,
+  via inbox WinRT and shell APIs.
+test_files: []