winipc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 628224ea1bed3bec0541f134c74f786132ffc060750d07af59e1f97f0273d484
+  data.tar.gz: af11bf3b0527555f5cc1df9542dee9b8e3c8249d52fbf3999e1b461028d052f5
+SHA512:
+  metadata.gz: a8c03faa73dcddedd6727f5784d311c361ebadd4c93efe16ef1519dbae81e6049bbccc5bdf580606338c55dc7d806dbe1ae026146e7a777547f100329b8da497
+  data.tar.gz: 7ec5eb17dc9d44200e40676b0425865f11a79e5e5faf11d33550e0ca8d2a1d3825bbf40773669640e838c11cda362158193b98c7ba8a684e82f7fa4296b72dea

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.0] - 2026-06-01
+
+Initial release.
+
+- **Named pipes** — `Winipc::Pipe.listen` (server with `#accept`/`#serve`) and
+  `Winipc::Pipe.connect` (connect-with-retry client); a duplex `Conn` with
+  `#read`/`#write` (byte mode) and `#read_message`/`#write_message` (message
+  mode). Overlapped I/O throughout: blocking calls release the GVL and are
+  cancelable, and run cooperatively under a fiber scheduler (winloop) by
+  offloading to a worker thread. The listener always keeps a pending instance so
+  clients never see a between-accepts gap.
+- **Shared memory** — `Winipc::SharedMemory.create`/`.open` over pagefile-backed
+  named file mappings, with bounds-checked `#read`/`#write`/`#flush`.
+- **Named synchronization** — `Winipc::Mutex`, `Winipc::Event`, and
+  `Winipc::Semaphore` with `create`/`open`, GVL-releasing interruptible waits,
+  and auto-releasing `#synchronize` block forms. Abandoned mutexes are surfaced.
+- **Secure by default** — pipe servers restrict access to the current user,
+  reject remote clients, and use `FILE_FLAG_FIRST_PIPE_INSTANCE`; handles are
+  non-inheritable; objects default to the per-session `Local\` namespace. An
+  explicit SDDL string or `:everyone` is opt-in.
+- Error taxonomy under `Winipc::Error` (`OSError` with `#code`, plus
+  `TimeoutError`, `NotFound`, `Exists`, `AccessDenied`, `BrokenPipe`, `PipeBusy`,
+  `Canceled`, `NotOwner`, `WouldExceedMax`, `ModeError`, `RangeError`, `Closed`,
+  `Abandoned`).
+
+Pure C extension over kernel32 + advapi32 (`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,154 @@
+# winipc
+
+**Windows local IPC for Ruby: named pipes, shared memory, and named synchronization — safe by default, and cooperative under a fiber scheduler.**
+
+`winipc` is a native extension that exposes the three pillars of Windows
+inter-process communication through an ergonomic, hard-to-misuse Ruby API:
+
+- **Named pipes** — a duplex server and a connect-with-retry client, byte or
+  message framed. Opened for overlapped I/O, so blocking calls release the GVL
+  and (under a fiber scheduler such as [winloop](https://rubygems.org/gems/winloop))
+  run **cooperatively** instead of stalling the loop.
+- **Shared memory** — pagefile-backed named regions (`CreateFileMapping`), with
+  bounds-checked reads and writes.
+- **Named synchronization** — cross-process **Mutex**, **Event**, and
+  **Semaphore**, with auto-releasing block forms.
+
+It is **secure by default**: pipe servers reject remote clients and restrict the
+pipe to the current user (closing the documented default ACL that grants
+`Everyone` read), the first instance is created with
+`FILE_FLAG_FIRST_PIPE_INSTANCE` so a squatter can't pre-own the name, and no
+handle is inheritable.
+
+## Requirements
+
+- **Windows** with a native **MSVC (mswin)** Ruby. Not supported on MinGW/UCRT.
+- Visual Studio 2017+ / Build Tools with the **Desktop development with C++** workload.
+
+## Install
+
+```sh
+gem install winipc
+```
+
+## Named pipes
+
+```ruby
+require "winipc"
+
+# Server (one process)
+Winipc::Pipe.listen("myapp/control") do |server|
+  server.serve do |conn|             # accept + yield + close, in a loop
+    request = conn.read(4096)
+    conn.write("ack: #{request}")
+  end
+end
+
+# Client (another process)
+Winipc::Pipe.connect("myapp/control", timeout: 5) do |c|
+  c.write("hello")
+  puts c.read(4096)                  # => "ack: hello"
+end
+```
+
+`read` returns `nil` at a clean EOF (peer closed), exactly like `IO#read`; a peer
+dying mid-stream raises `Winipc::BrokenPipe`. **Message mode** preserves message
+boundaries:
+
+```ruby
+Winipc::Pipe.listen("svc", mode: :message) { |s| c = s.accept; c.read_message }
+Winipc::Pipe.connect("svc", mode: :message) { |c| c.write_message("one whole message") }
+```
+
+### Cooperative under winloop
+
+Because pipe handles are overlapped and the blocking calls release the GVL, a
+server and many clients can run as fibers on a single IOCP loop:
+
+```ruby
+require "winloop"
+Winloop.run do
+  Fiber.schedule { Winipc::Pipe.listen("svc") { |s| s.serve { |c| c.write(c.read(1024)) } } }
+  Fiber.schedule { Winipc::Pipe.connect("svc") { |c| c.write("hi"); c.read(1024) } }
+end
+```
+
+Under a scheduler, each blocking winipc call is offloaded to a worker thread and
+the calling fiber parks, so the loop keeps serving other fibers. With no
+scheduler, the same calls just block the calling thread (releasing the GVL).
+
+## Shared memory
+
+```ruby
+# Process A
+shm = Winipc::SharedMemory.create("myapp/buffer", 4096)
+shm.write(0, "shared payload")
+
+# Process B
+shm = Winipc::SharedMemory.open("myapp/buffer")
+shm.read(0, 14)                      # => "shared payload"
+```
+
+Reads and writes are bounds-checked (`Winipc::RangeError` outside the region).
+Pair shared memory with a named `Event` to hand off deterministically rather
+than polling.
+
+> **Size note:** the creator's `#size` is exactly the requested size; an
+> **opener**'s `#size` is the page-rounded mapped region (Windows rounds a
+> mapping up to the page boundary and doesn't record the logical size), so an
+> opener may read/write within the rounded region. If the exact length matters,
+> carry it out-of-band (e.g. store it in the first bytes of the region).
+
+## Named synchronization
+
+```ruby
+# Cross-process mutex
+m = Winipc::Mutex.create("myapp/lock")
+m.synchronize { critical_section }   # always released, even on exception
+
+# Event (one process waits, another signals)
+ev = Winipc::Event.create("myapp/ready", manual_reset: true)
+ev.wait(timeout: 10)                 # => true (signaled) / false (timed out)
+ev.signal
+
+# Counting semaphore
+sem = Winipc::Semaphore.create("myapp/slots", initial: 3, maximum: 3)
+sem.synchronize { use_a_slot }
+```
+
+`Mutex` is owned by the acquiring **thread**, so its waits are not offloaded to a
+worker (they release the GVL but, under a fiber scheduler, block the loop for the
+duration). Use `Event`/`Semaphore` — which any thread may wait on and signal —
+for fiber-cooperative coordination. An abandoned mutex (its holder died) is
+surfaced as `Winipc::Abandoned` / `#abandoned?` rather than silently ignored.
+
+## Errors
+
+```
+StandardError
+└─ Winipc::Error
+    ├─ Winipc::OSError          # a Windows API failed; #code is GetLastError
+    │   ├─ Winipc::TimeoutError   ├─ Winipc::BrokenPipe   ├─ Winipc::NotOwner
+    │   ├─ Winipc::NotFound       ├─ Winipc::PipeBusy     └─ Winipc::WouldExceedMax
+    │   ├─ Winipc::Exists         ├─ Winipc::Canceled
+    │   └─ Winipc::AccessDenied
+    ├─ Winipc::ModeError        # byte/message-mode misuse
+    ├─ Winipc::RangeError       # shared-memory access out of bounds
+    ├─ Winipc::Closed           # operating on a closed object
+    └─ Winipc::Abandoned        # a mutex's previous owner died holding it
+```
+
+## Notes
+
+- **Names** are bare (`"myapp/control"`); winipc maps them to `\\.\pipe\…` for
+  pipes and the `Local\` kernel namespace for shared memory / sync objects (pass
+  `scope: :global` for the `Global\` namespace, which may need privileges).
+- Every kernel handle lives in a wrapper whose finalizer closes it, so a
+  forgotten `#close` never leaks — but closing explicitly is good manners.
+- Blocking calls (`accept`, `read`, `write`, `wait`/`lock`/`acquire`) release the
+  GVL and are interruptible (`Thread#kill`, `Ctrl-C`, `Timeout`).
+- **Windows/MSVC only.** Links `kernel32` + `advapi32`, built with `cl.exe`.
+
+## License
+
+[MIT](LICENSE.txt).

data/ext/winipc/extconf.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the winipc extension — Windows local IPC (named pipes,
+# shared memory / file mappings, and named synchronization objects).
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    winipc requires a native Windows MSVC (mswin) Ruby — it binds Win32 named
+    pipes, file-mapping shared memory, and named synchronization objects, and is
+    built with cl.exe. Your Ruby is "#{RbConfig::CONFIG['arch']}".
+  MSG
+end
+
+# kernel32 (pipes / file mappings / sync objects) is linked by default.
+# advapi32 provides ConvertStringSecurityDescriptorToSecurityDescriptorW for the
+# safe-by-default security descriptors. Pure C — no -EHsc.
+$libs = [$libs, "advapi32.lib"].join(" ")
+
+create_makefile("winipc/winipc")