tracepath 0.1.0

data/lib/tracepath/version.rb

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

data/lib/tracepath.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "tracepath/version"
+require_relative "tracepath/errors"
+require_relative "tracepath/models"
+require_relative "tracepath/options"
+require_relative "tracepath/resolver"
+require_relative "tracepath/packet"
+require_relative "tracepath/transport"
+require_relative "tracepath/runner"
+
+module Tracepath
+  class << self
+    def trace(target, cancellation: nil, rate_limit: 50.0, on_event: nil, **options)
+      unless on_event.nil? || on_event.respond_to?(:call)
+        raise ArgumentError, "on_event must be callable"
+      end
+      request = target.is_a?(Request) ? target : Request.new(target)
+      settings = Options.new(**options.merge(request.options))
+      token = cancellation_token(cancellation)
+      limiter = RateLimiter.new(rate_limit)
+      events = Queue.new
+      progress = on_event && ->(event) { events << [:progress, event] }
+      worker = start_worker(events, token) do
+        result = Runner.new(request: request, options: settings, cancellation: token, limiter: limiter,
+                            on_event: progress).run do |hop|
+          events << [:hop, hop]
+        end
+        events << [:result, result]
+      end
+      loop do
+        kind, value = events.pop
+        case kind
+        when :progress then on_event.call(value)
+        when :hop then yield(value) if block_given?
+        when :result then return value
+        when :exception then raise value
+        end
+      end
+    ensure
+      token&.cancel
+      worker&.join
+    end
+
+    def trace_many(targets, concurrency: 4, cancellation: nil, rate_limit: 50.0, **options)
+      unless concurrency.is_a?(Integer) && (1..256).cover?(concurrency)
+        raise ArgumentError, "concurrency must be an integer in 1..256"
+      end
+      raise ArgumentError, "targets must be an enumerable of hostnames or Requests" unless targets.respond_to?(:map)
+      # Validate the entire plan before starting any worker or resolver.
+      Options.new(**options)
+      entries = targets.map do |target|
+        request = target.is_a?(Request) ? target : Request.new(target)
+        [request, Options.new(**options.merge(request.options))]
+      end.to_a
+      token = cancellation_token(cancellation)
+      limiter = RateLimiter.new(rate_limit)
+      started = Clock.now
+      results = Array.new(entries.length)
+      return BatchResult.new(results: results, duration: 0.0) if entries.empty?
+      events = Queue.new
+      work = Queue.new
+      entries.each_with_index { |entry, index| work << [entry, index] }
+      workers = []
+      [concurrency, entries.size].min.times do
+        workers << start_worker(events, token) do
+          loop do
+            item = begin
+                     work.pop(true)
+                   rescue ThreadError
+                     break
+                   end
+            (request, settings), index = item
+            result = Runner.new(request: request, options: settings, cancellation: token, limiter: limiter).run
+            events << [:result, result, index]
+          end
+        end
+      end
+      entries.size.times do
+        kind, value, index = events.pop
+        raise value if kind == :exception
+        results[index] = value
+        yield(value, index) if block_given?
+      end
+      BatchResult.new(results: results, duration: Clock.now - started)
+    ensure
+      token&.cancel
+      workers&.each(&:join)
+    end
+
+    private
+
+    def cancellation_token(parent)
+      if !parent.nil? && !parent.is_a?(CancellationToken)
+        raise ArgumentError, "cancellation must be a Tracepath::CancellationToken"
+      end
+      CancellationToken.new(parent: parent)
+    end
+
+    def start_worker(events, token, &block)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        block.call
+      rescue Exception => error # transfer the original exception to the caller thread
+        token.cancel
+        events << [:exception, error]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: tracepath
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tracepath contributors
+bindir: exe
+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'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: resolv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: IPv4/IPv6 UDP, ICMP and TCP SYN traceroute with immutable observations,
+  cancellation, and structured batch results.
+executables:
+- tracepath
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/platforms.md
+- docs/releasing.md
+- docs/verification.md
+- exe/tracepath
+- lib/tracepath.rb
+- lib/tracepath/cli.rb
+- lib/tracepath/cli/elevated.rb
+- lib/tracepath/cli/privilege_check.rb
+- lib/tracepath/cli/privileges.rb
+- lib/tracepath/cli/text_output.rb
+- lib/tracepath/errors.rb
+- lib/tracepath/models.rb
+- lib/tracepath/options.rb
+- lib/tracepath/packet.rb
+- lib/tracepath/pcap.rb
+- lib/tracepath/resolver.rb
+- lib/tracepath/runner.rb
+- lib/tracepath/transport.rb
+- lib/tracepath/version.rb
+homepage: https://github.com/gatework/tracepath
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gatework/tracepath
+  changelog_uri: https://github.com/gatework/tracepath/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Native Ruby traceroute and bounded batch network diagnostics
+test_files: []