packet-capture-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 918a30c029072ad74463af9150cf13a6c039ed04a8361babac76b0fe09264071
+  data.tar.gz: 2da7769cd7439a1cc634854816f621d73c8ddbe3052f985233986c75c644ee40
+SHA512:
+  metadata.gz: 8663e988c524ee54b61cf037dcb08a9da1d38af07a28b2f447090686961909057d2973c2cb78c266bb6f4956fe44d763af0f835a62e30b06a46f8f4ae5d43ae1
+  data.tar.gz: c266eb7afec0eb59095e1770781e2d79bba5f0223491ad565b5e65585848dfa8dc5eec4333f750ffaad26f8a7444b6585d639c98533b191c27985db01b373e34

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Titanfyre
+
+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,12 @@
+# Packet-Capture-SDK Ruby SDK
+
+`gem install packet-capture-sdk`
+
+Windows x64 Ruby3.1+.
+
+```ruby
+require "packet_capture_sdk"
+PacketCaptureSDKSDK::Client.open { |client| p client.call("status") }
+```
+
+[API and operation schema](docs/API.md). Matching driver installed separately.

data/docs/API.md

@@ -0,0 +1,23 @@
+# Packet-Capture-SDK operation schema
+
+The unchanged product C++ SDK is called directly. Operations: `check`, `parse_frame`, `authorize`, `adapters`, `start`, `stop`, `status`, `receive`, `send`, `close`. The dispatch source in `Bridge.cpp` lists exact argument keys and maps every operation to the original public SDK. Protocol structs retain their public-header field names, including case. UInt64 and Int64 fields are decimal strings; fixed arrays accept at most their capacity and omitted fields initialize to zero. Unknown fields and out-of-range values are rejected. SDK validators apply original protocol constraints.
+
+Wire types and fields:
+
+- `PC_ADAPTER`: id, luid, ifindex, running, mac, reserved, name
+- `PC_ADAPTERS`: version, count, adapters
+- `PC_SELECTION`: adapter, directions, reserved
+- `PC_STATE`: version, size, active, authorized, selected, captured, overwritten, sent, send_failed, frequency, queued, pending_sends
+- `PC_EVENT`: sequence, qpc, adapter, direction, length, original_length, reserved, data, padding
+- `PC_BATCH`: version, count, state, events
+- `PC_FRAME`: length, reserved, data, padding
+- `TITAN_AUTHORIZATION_CHALLENGE`: magic, version, product, duration_seconds, nonce
+- `TITAN_AUTHORIZATION_TOKEN`: permission, signature
+
+Only explicit start/connect/policy calls start the corresponding operation. The C ABI session constructor is inert; one active session per product DLL. Always close. Capture receives are bounded when the native API accepts a timeout. SDK original licensing/trial checks remain unchanged. No driver is installed by packages.
+
+Tests exercise synthetic wire inputs using the real production SDK validation/formatting helpers, rejected arguments, exact unsigned values and inert session lifecycle. No live capture, policy application, storage fault, traffic modification or driver activation is performed by these tests. Operational driver paths require a separate integration environment.
+
+## Language client
+
+The client calls the native SDK directly. Use the call method with an operation name and argument object. Calls are synchronous; only operations exposing a receive timeout are capped at100ms; use an application worker for responsive UI/event loops. Explicitly close the client after use. 64-bit identifiers and counters are decimal strings. Native errors expose their Windows code. Matching driver and licensing are separate requirements.

data/docs/LICENSE.nlohmann-json

@@ -0,0 +1,21 @@
+MIT License 
+
+Copyright (c) 2013-2025 Niels Lohmann
+
+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/lib/packet_capture_sdk.rb

@@ -0,0 +1,46 @@
+require 'json'
+require 'fiddle'
+require 'thread'
+module PacketCaptureSDKSDK
+  class NativeError < StandardError
+    attr_reader :code
+    def initialize(code,message);@code=code;super(message);end
+  end
+  class Client
+    def self.open(library_path: nil)
+      client=new(library_path: library_path)
+      return client unless block_given?
+      begin;yield client;ensure;client.close;end
+    end
+    def initialize(library_path: nil)
+      raise 'Windows x64 required' unless Fiddle::SIZEOF_VOIDP==8 && RUBY_PLATFORM.match?(/mingw|mswin/)
+      @library=Fiddle::Handle.new(library_path || ENV['PACKET_CAPTURE_SDK_SDK_NATIVE_PATH'] || File.expand_path('../native/PacketCaptureSDKJsonSDK.dll',__dir__))
+      @mutex=Mutex.new
+      @open=Fiddle::Function.new(@library['packet_capture_sdk_json_open'],[Fiddle::TYPE_VOIDP],Fiddle::TYPE_INT)
+      @close=Fiddle::Function.new(@library['packet_capture_sdk_json_close'],[Fiddle::TYPE_LONG_LONG],Fiddle::TYPE_INT)
+      @call=Fiddle::Function.new(@library['packet_capture_sdk_json_call'],[Fiddle::TYPE_LONG_LONG,Fiddle::TYPE_VOIDP,Fiddle::TYPE_INT],Fiddle::TYPE_VOIDP)
+      @free=Fiddle::Function.new(@library['packet_capture_sdk_json_free'],[Fiddle::TYPE_VOIDP],Fiddle::TYPE_VOID)
+      out=Fiddle::Pointer.malloc(8,Fiddle::RUBY_FREE);out[0,8]=[0].pack('Q<');code=@open.call(out);raise NativeError.new(code,'Cannot open SDK') if code!=0
+      @session=out[0,8].unpack1('Q<')
+    end
+    def call(operation,arguments={})
+      payload=JSON.generate({operation:operation,arguments:arguments}).encode('UTF-8')
+      raise ArgumentError,'Request exceeds 32 MiB' if payload.bytesize>32*1024*1024
+      @mutex.synchronize do
+        raise 'SDK is closed' if @session==0
+        pointer=@call.call(@session,payload,payload.bytesize);raise NoMemoryError,'Native response allocation failed' if pointer.null?
+        begin;response=JSON.parse(pointer.to_s);ensure;@free.call(pointer);end
+        raise NativeError.new(response['code'],response['message']) unless response['ok']
+        response['result']
+      end
+    end
+    def close
+      @mutex.synchronize do
+        if @session!=0
+          code=@close.call(@session);raise NativeError.new(code,'Native close failed') if code!=0
+          @session=0
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: packet-capture-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- TitanCSA
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Product native SDK operations through a UTF-8 JSON C ABI; driver installed
+  separately.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- docs/API.md
+- docs/LICENSE.nlohmann-json
+- lib/packet_capture_sdk.rb
+- native/PacketCaptureSDKJsonSDK.dll
+homepage: https://github.com/titanfyre/Packet-Capture-SDK
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/titanfyre/Packet-Capture-SDK
+  documentation_uri: https://github.com/titanfyre/Packet-Capture-SDK/tree/main/Packet-Capture-SDK-Ruby-rubygems/docs
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Windows x64 Packet-Capture-SDK direct SDK
+test_files: []