towel 0.1.0

data/lib/towel/environment.rb

@@ -0,0 +1,64 @@
+module Towel
+  # Helpers to collect the environment-specific details for invocations.
+  module Environment
+    # Environment variable that, if set, defines the source control management
+    # revision that is reported to Towel. See `Invocation.revision` in
+    # towel.proto for more details.
+    REVISION_ENV = "TOWEL_REVISION".freeze
+
+    # Environment variable that, if set, defines what other environment
+    # variables should be redacted.
+    REDACT_ENV = "TOWEL_REDACT".freeze
+
+    # Value that is substituted for environment variables that have been
+    # redacted.
+    REDACTED = "REDACTED".freeze
+
+    # The current platform that Towel is running on.
+    def self.platform
+      platform = Towel::V1alpha::Platform.new
+      uname = Etc.uname
+      platform.os = uname[:sysname]
+      platform.os_version = uname[:release]
+      platform.arch = uname[:machine]
+      return platform
+    end
+
+    # The hostname of this machine.
+    def self.hostname
+      Socket.gethostname
+    end
+
+    # The OS user that this process is running as.
+    def self.user
+      Etc.getlogin
+    end
+
+    # The current working directory.
+    def self.working_dir
+      Dir.getwd
+    end
+
+    # The arguments used to launch this process.
+    def self.argv
+      [$0].concat(ARGV)
+    end
+
+    # The environment variables set for this process.
+    def self.env_vars
+      redacted = ENV.fetch(REDACT_ENV, "").split(",").map(&:strip)
+      ENV.to_h do |name, value|
+        if redacted.include?(name)
+          [name, REDACTED]
+        else
+          [name, value]
+        end
+      end
+    end
+
+    # The version control system (VCS) revision for the code that is running.
+    def self.revision
+      ENV.fetch(REVISION_ENV, "")
+    end
+  end
+end

data/lib/towel/log.rb

@@ -0,0 +1,100 @@
+require "concurrent-ruby"
+
+module Towel
+  class Log
+    # Logs must be associated with an invocation.
+    NAME_FORMAT = /invocations\/[^\/]+\/logs\/[^\/]+/
+
+    # How long to wait for more log entries before calling `AppendLog`. This
+    # tries to batch log lines together as opposed to making a call for each
+    # log line individually.
+    FLUSH_INTERVAL_SECONDS = 0.1
+
+    # How many log lines to send at a time. If there are more than this, they
+    # will be broken up into several `AppendLog` calls.
+    FLUSH_COUNT = 100
+
+    attr_reader :name
+
+    def initialize(name, stub)
+      unless name =~ NAME_FORMAT
+        raise ArgumentError, "Log name #{name} is invalid"
+      end
+      raise ArgumentError, "Stub must be provided" unless stub
+      @name = name
+      @stub = stub
+      @entries = Queue.new
+      @entry_id = Concurrent::AtomicFixnum.new(-1)
+      @flush_mutex = Mutex.new
+      @flush_timer_mutex = Mutex.new
+      @flush_timer = nil
+
+      # Create the log
+      log = Towel::V1alpha::Log.new
+      log.name = @name
+      request = Towel::V1alpha::CreateLogRequest.new
+      request.log = log
+      @stub.create_log(request)
+    end
+
+    def context
+      Thread.current["towel_context_#{object_id}"]
+    end
+
+    def context=(context)
+      Thread.current["towel_context_#{object_id}"] = context
+    end
+
+    def <<(line)
+      entry = Towel::V1alpha::LogEntry.new
+      entry.entry_id = @entry_id.increment
+      entry.log_time = Time.now.utc
+      entry.parent = context if context
+      entry.contents = line
+
+      @entries << entry
+
+      # Set up a flush to happen momentarily, allowing other lines to possibly
+      # be flushed together with this one.
+      @flush_timer_mutex.synchronize do
+        unless @flush_timer
+          @flush_timer = Concurrent::ScheduledTask.execute(
+            FLUSH_INTERVAL_SECONDS
+          ) { flush }
+        end
+      end
+    end
+
+    def close
+      flush
+      Thread.current["towel_context_#{object_id}"] = nil
+    end
+
+    # Ensure that entries get written out to Towel.
+    def flush
+      @flush_mutex.synchronize do
+        # Acknowledge the flush timer by unsetting it, if it exists.
+        @flush_timer_mutex.synchronize do
+          @flush_timer.cancel if @flush_timer
+          @flush_timer = nil
+        end
+
+        until @entries.empty?
+          request = Towel::V1alpha::AppendLogRequest.new
+          request.name = @name
+          i = 0
+          while i < FLUSH_COUNT
+            i += 1
+            begin
+              entry = @entries.pop(true)
+            rescue ThreadError # Raised if the queue is empty
+              break
+            end
+            request.entries << entry
+          end
+          @stub.append_log(request)
+        end
+      end
+    end
+  end
+end

data/lib/towel/log_io.rb

@@ -0,0 +1,71 @@
+module Towel
+  # An IO-like object that logs to Towel. Sits on top of Log. This relationship
+  # is inverted compared to most IO class structures, but log lines/entries are
+  # the fundamental unit of Towel. This class is merely an adapter to collect
+  # logs from IO streams like `$stdout` and `$stderr`.
+  class LogIO
+    def initialize(log)
+      raise ArgumentError, "Log must be specified" unless log
+      @log = log
+      @buffer = ""
+      @write_mutex = Mutex.new
+    end
+
+    def context=(context)
+      @log.context = context
+    end
+
+    def putc(c)
+      if c.is_a?(String)
+        write(c[0])
+      else
+        write(c.chr)
+      end
+    end
+
+    def puts(*args)
+      if args.empty?
+        write($/)
+      else
+        args.each do |arg|
+          arg = arg.to_s
+          if arg.end_with?($/)
+            write(arg)
+          else
+            write(arg, $/)
+          end
+        end
+      end
+    end
+
+    def write(*args)
+      @write_mutex.synchronize do
+        bytes = 0
+        args.each do |arg|
+          @buffer << arg
+          bytes += arg.bytesize
+        end
+
+        remaining = ""
+        @buffer.each_line do |line|
+          if line.end_with?($/)
+            @log << line
+          else
+            remaining = line
+          end
+        end
+        @buffer = remaining
+
+        bytes
+      end
+    end
+
+    def flush
+      @log.flush
+    end
+
+    def close
+      @log.close
+    end
+  end
+end

data/lib/towel/session.rb

@@ -0,0 +1,199 @@
+module Towel
+  # A session keeps track of an invocation throughout its lifespan. It is meant
+  # to be a helper to framework-specific implementations by providing a more
+  # convenient API over the raw gRPC calls.
+  class Session
+    def initialize(config = nil)
+        @config = config || Towel::Configuration.read
+        @stub = create_stub
+        @project = [
+          "organizations",
+          @config["collector"]["organization"],
+          "projects",
+          @config["collector"]["project"]
+        ].join "/"
+        @invocation = nil
+        @groups = {}
+        @group_id = -1
+        @results = {}
+        @result_id = -1
+        @logs = {}
+    end
+
+    # Creates a new invocation. Returns the invocation URL at which users may
+    # view results. This must be called before other methods.
+    def create_invocation
+        invocation = Towel::V1alpha::Invocation.new
+        invocation.project = @project
+        invocation.labels["language"] = "ruby"
+        @config["labels"].each {|k, v| invocation.labels[k] = v }
+        invocation.start_time = Time.now.utc
+
+        # Add environment-specific information
+        invocation.platform = Towel::Environment.platform
+        invocation.hostname = Towel::Environment.hostname
+        invocation.user = Towel::Environment.user
+        invocation.working_dir = Towel::Environment.working_dir
+        invocation.argv.concat(Towel::Environment.argv)
+        Towel::Environment.env_vars.each do |name, value|
+          invocation.env_vars[name] = value
+        end
+        invocation.revision = Towel::Environment.revision
+
+        request = Towel::V1alpha::CreateInvocationRequest.new
+        request.invocation = invocation
+
+        @invocation = @stub.create_invocation(request)
+
+        @invocation.url
+    end
+
+    # Creates a result under a specified group and mark it as running. Returns
+    # the resource name of the result, which can be used to set a Log context.
+    def create_result(group, name, display_name: nil)
+      group_id = find_or_create_group(group)
+
+      result = Towel::V1alpha::Result.new
+
+      if @results.key?([group_id, name])
+        raise Error, "Result already has been created for '#{name}'"
+      else
+        result_id = @result_id += 1
+        @results[[group_id, name]] = result_id
+      end
+
+      result.name = [
+        @invocation.name,
+        "groups",
+        group_id,
+        "results",
+        result_id
+      ].join "/"
+      result.display_name = display_name || name
+      result.start_time = Time.now.utc
+      result.state = Towel::V1alpha::ResultState::RUNNING
+
+      request = Towel::V1alpha::CreateResultRequest.new
+      request.result = result
+
+      @stub.create_result(request)
+
+      ["groups", group_id, "results", result_id].join "/"
+    end
+
+    # Updates a result with its outcome.
+    def update_result(group, name, state:, duration: nil, description: nil)
+      group_id = find_group(group)
+      unless @results.key?([group_id, name])
+        raise Error, "Cannot find result '#{name}'"
+      end
+      result_id = @results[[group_id, name]]
+
+      result = Towel::V1alpha::Result.new
+      update_mask = Google::Protobuf::FieldMask.new
+
+      result.name = [
+        @invocation.name,
+        "groups",
+        group_id,
+        "results",
+        result_id
+      ].join "/"
+
+      update_mask.paths << "state"
+      result.state = state
+
+      if !duration.nil?
+        update_mask.paths << "duration"
+        result.duration = duration
+      end
+
+      if !description.nil?
+        update_mask.paths << "description"
+        result.description = description
+      end
+
+      request = Towel::V1alpha::UpdateResultRequest.new
+      request.result = result
+      request.update_mask = update_mask
+
+      @stub.update_result(request)
+    end
+
+    # Create a new log with a given name. This can be used as-is or wrapped in a
+    # LogIO wrapper and used in place of a IO stream.
+    def create_log(name)
+      raise Error, "Log '#{name}' already exists" if @logs.key?(name)
+      resource_name = [@invocation.name, "logs", name].join "/"
+      @logs[name] = Log.new(resource_name, @stub)
+    end
+
+    # Mark an invocation as finished (ran to termination without being
+    # cancelled). Do not call this and `#cancel` on a given Session. All
+    # outstanding logs will be flushed and closed as part of this.
+    def finish_invocation
+      @logs.each { |name, log| log.close }
+
+      request = Towel::V1alpha::FinishInvocationRequest.new
+      request.name = @invocation.name
+      request.end_time = Time.now.utc
+
+      @stub.finish_invocation(request)
+    end
+
+    # Mark an invocation as cancelled. Do not call this and `#finish` on a
+    # given Session.
+    def cancel_invocation
+      request = Towel::V1alpha::CancelInvocationRequest.new
+      request.name = @invocation.name
+
+      @stub.cancel_invocation(request)
+    end
+
+    private
+
+    # Returns a Collector stub that the rest of this class can use to
+    # communicate with Towel.
+    def create_stub
+        ssl_credentials = GRPC::Core::ChannelCredentials.new
+        bearer_credentials = GRPC::Core::CallCredentials.new(proc {
+          { authorization: "Bearer #{@config["auth"]["api_key"]}" }
+        })
+        credentials = ssl_credentials.compose(bearer_credentials)
+
+        Towel::V1alpha::Collector::Stub.new(
+          @config["collector"]["address"],
+          credentials
+        )
+    end
+
+    # Finds a group by name and attempts to create it if it does not exist.
+    # Returns the ID of the group. Most users of Session will call
+    # `#create_result` instead, which calls this behind the scenes.
+    def find_or_create_group(name)
+      if @groups.key?(name)
+        @groups[name]
+      else
+        # This group doesn't exist yet, so let's create it.
+        group_id = @group_id += 1
+
+        group = Towel::V1alpha::Group.new
+        group.name = [@invocation.name, "groups", group_id].join "/"
+        group.display_name = name
+        request = Towel::V1alpha::CreateGroupRequest.new
+        request.group = group
+
+        @stub.create_group(request)
+        @groups[name] = group_id
+        group_id
+      end
+    end
+
+    # Finds a previously created group by name. Raises `Towel::Error` if the
+    # group does not exist.
+    def find_group(name)
+      raise Error, "Cannot find group '#{name}'" unless @groups.key?(name)
+      @groups[name]
+    end
+  end
+end

data/lib/towel/version.rb

@@ -0,0 +1,3 @@
+module Towel
+  VERSION = "0.1.0"
+end

data/lib/towel.rb

@@ -0,0 +1,30 @@
+# Standard library
+require "etc"
+require "socket"
+
+# Gems
+require "grpc"
+require "toml"
+
+# Generated Protocol Buffer/gRPC definitions
+require "towel/v1alpha/collector_pb"
+require "towel/v1alpha/collector_services_pb"
+require "towel/v1alpha/towel_pb"
+
+require "towel/configuration"
+require "towel/environment"
+require "towel/log"
+require "towel/log_io"
+require "towel/session"
+require "towel/version"
+
+module Towel
+  class Error < StandardError; end
+
+  # Returns whether Towel has been disabled.
+  def self.disabled?
+    %w[DISABLE_TOWEL TOWEL_DISABLE].any? do |key|
+      ENV.key?(key) && ENV[key] =~ /1|t(rue)?|y(es)?|disabled?/i
+    end
+  end
+end

data/towel.gemspec

@@ -0,0 +1,45 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "towel/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "towel"
+  spec.version       = Towel::VERSION
+  spec.authors       = ["Andrew Smith"]
+  spec.email         = ["andrew@velvet.software"]
+
+  spec.summary       = "Towel is a test result collector"
+  spec.description   = <<END
+Towel collects test results as they run, reporting them to towel.dev for easier
+inspection, debugging, and sharing.
+END
+  spec.homepage      = "https://towel.dev"
+  spec.license       = "MIT"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://bitbucket.org/VelvetSoftware/towel-ruby"
+    spec.metadata["changelog_uri"] = "https://bitbucket.org/VelvetSoftware/towel-ruby/src/master/CHANGELOG.md"
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.files         += Dir["generated/**/*"]
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib", "generated"]
+
+  spec.add_dependency "concurrent-ruby", "~> 1.1"
+  spec.add_dependency "grpc", "~> 1.22"
+  spec.add_dependency "toml", "~> 0.2"
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "fakefs", "~> 0.20"
+  spec.add_development_dependency "grpc-tools", "~> 1.22"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end