glazed 0.1.0

data/lib/glazed/dialect/actions.rb

@@ -0,0 +1,95 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/dialect'
+
+module Glazed
+  module Dialect
+    # Edits that interactions and runbook steps apply to a text buffer.
+    #
+    # A String is shorthand for {Append} and nil does nothing.
+    module Actions
+      # Action applying content to a buffer.
+      class Content
+        # @param content [String] text the action carries
+        #: (content: String) -> void
+        def initialize(content:)
+          @content = content.dup.freeze #: String
+        end
+
+        # @return [String] text the action carries
+        #: String
+        attr_reader :content
+
+        # @param other [Object] object to compare
+        # @return [Boolean] whether other is the same action with the same content
+        #: (untyped other) -> bool
+        def ==(other) = other.class == self.class && other.content == content
+
+        alias eql? ==
+
+        # @return [Integer] hash consistent with {#==}
+        #: () -> Integer
+        def hash = [self.class, content].hash
+      end
+
+      # Appends content to the buffer.
+      class Append < Content; end
+
+      # Replaces the whole buffer with content.
+      class Replace < Content; end
+
+      # Applies several actions in order.
+      class Multi
+        # @param actions [Array<Append, Replace, Multi, String, nil>] actions, flattened and normalised
+        #: (*Actions::action? actions) -> void
+        def initialize(*actions)
+          @actions = actions.flat_map { Multi.normalize(it) }.freeze #: Array[Append | Replace]
+        end
+
+        # @return [Array<Append, Replace>] flattened actions
+        #: Array[Append | Replace]
+        attr_reader :actions
+
+        # @param action [Append, Replace, Multi, String, nil] action to normalise
+        # @return [Array<Append, Replace>] equivalent plain actions
+        #: (Actions::action? action) -> Array[Append | Replace]
+        def self.normalize(action)
+          case action
+          when nil then []
+          when String then [Append.new(content: action)]
+          when Multi then action.actions
+          else [action]
+          end
+        end
+
+        # @param other [Object] object to compare
+        # @return [Boolean] whether other holds the same actions
+        #: (untyped other) -> bool
+        def ==(other) = other.is_a?(Multi) ? other.actions == actions : false
+      end
+
+      #: type action = Append | Replace | Multi | String
+
+      # Applies an action to a buffer.
+      #
+      # @param buffer [String] text to edit
+      # @param action [Append, Replace, Multi, String, nil] action to apply
+      # @return [String] the edited text, a new string
+      # @example
+      #   Actions.apply("a", Actions::Append.new(content: "b")) #=> "ab"
+      #: (String buffer, Actions::action? action) -> String
+      def self.apply(buffer, action)
+        Multi.normalize(action).inject(buffer.dup) do |result, step|
+          case step
+          when Append then result << step.content
+          when Replace then step.content.dup
+          else step #: absurd
+          end
+        end
+      end
+    end
+  end
+end

data/lib/glazed/dialect/communication_config.rb

@@ -0,0 +1,63 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/dialect'
+
+module Glazed
+  module Dialect
+    # How a dialect talks to a device over one transport.
+    class CommunicationConfig
+      #: type hook = ^(Run run) -> void
+
+      #: () -> void
+      def initialize
+        @exec = false #: bool
+        @pty_options = {} #: Hash[Symbol, untyped]
+        @username_prompt = nil #: Regexp?
+        @password_prompt = nil #: Regexp?
+        @post_login_hooks = [] #: Array[CommunicationConfig::hook]
+        @pre_logout_hooks = [] #: Array[CommunicationConfig::hook]
+      end
+
+      # @return [Boolean] run each command on its own exec channel when the transport supports it
+      #: bool
+      attr_accessor :exec
+      # @return [Hash{Symbol => Object}] PTY settings such as :term and :chars_wide, over the transport's defaults
+      #: Hash[Symbol, untyped]
+      attr_reader :pty_options
+
+      # @return [Regexp, nil] prompt for the user name; when set, the session logs in by answering it
+      #: Regexp?
+      attr_accessor :username_prompt
+      # @return [Regexp, nil] prompt for the password
+      #: Regexp?
+      attr_accessor :password_prompt
+      # @return [Array<Proc>] hooks run after login, in order
+      #: Array[CommunicationConfig::hook]
+      attr_reader :post_login_hooks
+      # @return [Array<Proc>] hooks run before logout, in order
+      #: Array[CommunicationConfig::hook]
+      attr_reader :pre_logout_hooks
+
+      # Adds a hook run after login and before the runbook.
+      #
+      # @yieldparam run [Run] the run in progress
+      # @return [void]
+      #: () { (Run run) -> void } -> void
+      def post_login(&hook)
+        @post_login_hooks << hook
+      end
+
+      # Adds a hook run after the runbook and before the connection closes.
+      #
+      # @yieldparam run [Run] the run in progress
+      # @return [void]
+      #: () { (Run run) -> void } -> void
+      def pre_logout(&hook)
+        @pre_logout_hooks << hook
+      end
+    end
+  end
+end

data/lib/glazed/dialect/interaction.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/dialect'
+require 'glazed/dialect/actions'
+
+module Glazed
+  module Dialect
+    #: type responder = ^(CliSession session, String buffer, MatchData match) -> Actions::action?
+    #: type data_filter = ^(String fragment) -> String
+
+    # Responds to a pattern appearing in the session buffer, such as a pager prompt.
+    class Interaction
+      # @param pattern [Regexp] pattern matched against the session buffer
+      # @param responder [Proc] called with the session, a copy of the buffer and the match; returns an action applied to the buffer
+      #: (pattern: Regexp, responder: Dialect::responder) -> void
+      def initialize(pattern:, responder:)
+        @pattern = pattern #: Regexp
+        @responder = responder #: Dialect::responder
+      end
+
+      # @return [Regexp] pattern matched against the session buffer
+      #: Regexp
+      attr_reader :pattern
+      # @return [Proc] responder returning an action applied to the buffer
+      #: Dialect::responder
+      attr_reader :responder
+    end
+  end
+end

data/lib/glazed/dialect/run.rb

@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/cli_session'
+require 'glazed/command_result'
+require 'glazed/dialect'
+require 'glazed/dialect/actions'
+require 'glazed/proto'
+require 'glazed/secret'
+
+module Glazed
+  module Dialect
+    # State of one runbook execution against one node.
+    class Run
+      # @param cli [CliSession] session to the node
+      # @param node [Proto::V1::Node] node being run against
+      # @param dialect [Class<Dialects::Base>] dialect of the node
+      #: (cli: CliSession, node: Proto::V1::Node, dialect: singleton(Dialects::Base)) -> void
+      def initialize(cli:, node:, dialect:)
+        @cli = cli #: CliSession
+        @node = node #: Proto::V1::Node
+        @dialect = dialect #: singleton(Dialects::Base)
+        @vars = {} #: Hash[Symbol, untyped]
+        @output = +'' #: String
+      end
+
+      # @return [CliSession] session to the node
+      #: CliSession
+      attr_reader :cli
+      # @return [Proto::V1::Node] node being run against
+      #: Proto::V1::Node
+      attr_reader :node
+      # @return [Class<Dialects::Base>] dialect of the node
+      #: singleton(Dialects::Base)
+      attr_reader :dialect
+      # @return [Hash{Symbol => Object}] scratch space shared by the steps of this run
+      #: Hash[Symbol, untyped]
+      attr_reader :vars
+      # @return [String] configuration collected so far
+      #: String
+      attr_reader :output
+
+      # Runs a command and passes its output, as bytes, through the dialect's
+      # output filters. Collected configuration must be UTF-8, so a dialect for
+      # a device using another encoding converts it in an output filter.
+      #
+      # @param line [String] command line
+      # @return [CommandResult] the filtered result, in UTF-8
+      # @raise [InvalidEncoding] when the filtered output is not valid UTF-8
+      #: (String line) -> CommandResult
+      def command(line)
+        result = cli.command(line)
+        filtered = dialect.output_filters.inject(result.output) { |text, output_filter| output_filter.call(text) }
+        output = filtered.dup.force_encoding(Encoding::UTF_8)
+        unless output.valid_encoding?
+          raise InvalidEncoding, "output of #{line.inspect} is not valid UTF-8; convert it in the dialect's filter_output"
+        end
+
+        CommandResult.new(command: result.command, output:)
+      end
+
+      # Applies an action to the collected configuration.
+      #
+      # @param action [Actions::Append, Actions::Replace, Actions::Multi, String, nil] action to apply
+      # @return [void]
+      #: (Actions::action? action) -> void
+      def emit(action)
+        @output = Actions.apply(@output, action)
+      end
+
+      # @param name [String] parameter name
+      # @return [String, nil] the node's parameter value
+      #: (String name) -> String?
+      def param(name) = node.params[name]
+
+      # @param name [String] secret name
+      # @return [Secret, nil] the node's secret
+      #: (String name) -> Secret?
+      def secret(name) = Secret.maybe(node.secrets[name])
+    end
+  end
+end

data/lib/glazed/dialect/runbook.rb

@@ -0,0 +1,97 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/command_result'
+require 'glazed/dialect'
+require 'glazed/dialect/actions'
+require 'glazed/dialect/run'
+
+module Glazed
+  module Dialect
+    # Ordered steps that collect configuration from a node.
+    class Runbook
+      #: type step_block = ^(Run run) -> void
+
+      # One step of a runbook.
+      class Step
+        # @param description [String] what the step does, such as its command line
+        # @param block [Proc] called with the run
+        #: (description: String, block: Runbook::step_block) -> void
+        def initialize(description:, block:)
+          @description = description #: String
+          @block = block #: Runbook::step_block
+        end
+
+        # @return [String] what the step does
+        #: String
+        attr_reader :description
+        # @return [Proc] called with the run
+        #: Runbook::step_block
+        attr_reader :block
+      end
+
+      # Collects steps for a runbook.
+      #
+      # @example
+      #   builder.command('show version') { |result| comment(result.output) }
+      #   builder.raw { |run| run.vars[:model] = run.command('show model').output }
+      class Builder
+        #: () -> void
+        def initialize
+          @steps = [] #: Array[Step]
+        end
+
+        # Adds a step that runs a command and emits what the block returns, or
+        # the output itself without a block.
+        #
+        # @param line [String] command line
+        # @yieldparam result [CommandResult] filtered command result
+        # @yieldreturn [Actions::Append, Actions::Replace, Actions::Multi, String, nil] action to emit
+        # @return [void]
+        #: (String line) ?{ (CommandResult result) -> Actions::action? } -> void
+        def command(line, &callback)
+          raw(line) do |run|
+            result = run.command(line)
+            run.emit(callback ? callback.call(result) : result.output)
+          end
+        end
+
+        # Adds a step that drives the run directly.
+        #
+        # @param description [String] what the step does
+        # @yieldparam run [Run] the run in progress
+        # @return [void]
+        #: (?String description) { (Run run) -> void } -> void
+        def raw(description = '', &block)
+          @steps << Step.new(description:, block:)
+        end
+
+        # @return [Runbook] runbook of the collected steps
+        #: () -> Runbook
+        def build = Runbook.new(steps: @steps.dup)
+      end
+
+      # @param steps [Array<Step>] steps in order
+      #: (steps: Array[Step]) -> void
+      def initialize(steps:)
+        @steps = steps.freeze #: Array[Step]
+      end
+
+      # @return [Array<Step>] steps in order
+      #: Array[Step]
+      attr_reader :steps
+
+      # Runs every step.
+      #
+      # @param run [Run] run to execute against
+      # @return [String] the collected configuration
+      #: (Run run) -> String
+      def execute(run)
+        steps.each { it.block.call(run) }
+        run.output
+      end
+    end
+  end
+end

data/lib/glazed/dialect/sensitive_pattern.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed/dialect'
+
+module Glazed
+  module Dialect
+    # Locates secrets in configuration text.
+    class SensitivePattern
+      #: type determiner = ^(MatchData match) -> (String | Range[Integer])?
+
+      # @param pattern [Regexp] pattern matched against the whole configuration
+      # @param determiner [Proc] returns the secret within a match, or its offsets in the configuration,
+      #   or nil when the match holds none
+      #: (pattern: Regexp, determiner: SensitivePattern::determiner) -> void
+      def initialize(pattern:, determiner:)
+        @pattern = pattern #: Regexp
+        @determiner = determiner #: SensitivePattern::determiner
+      end
+
+      # @return [Regexp] pattern matched against the whole configuration
+      #: Regexp
+      attr_reader :pattern
+      # @return [Proc] returns the secret within a match, or its offsets
+      #: SensitivePattern::determiner
+      attr_reader :determiner
+    end
+  end
+end

data/lib/glazed/dialect.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+
+module Glazed
+  # Building blocks of the dialect DSL. Dialects themselves live in {Dialects}.
+  module Dialect
+  end
+end

data/lib/glazed/dialects/awplus.rb

@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Derived from Oxidized (https://github.com/ytti/oxidized) lib/oxidized/model/awplus.rb,
+# Copyright 2013-2015 Saku Ytti, Samer Abdel-Hafez and Oxidized contributors,
+# licensed under the Apache License, Version 2.0. Modified for the glazed dialect API.
+
+require 'glazed/dialects/base'
+
+module Glazed
+  module Dialects
+    # Allied Telesis AlliedWare Plus.
+    class Awplus < Base
+      prompt(/^(\r?[\w.@:\/-]+[#>]\s?)$/)
+      comment_prefix '! '
+
+      interact(/--More--/) do |cli, _buffer, match|
+        cli.write(' ')
+        Actions::Replace.new(content: match.pre_match + match.post_match)
+      end
+
+      filter_data { |fragment| fragment.gsub("\e[7m\e[m", '').delete("\r") }
+
+      sensitive_pattern(/^snmp-server community\s+(\S+)/) { it[1] }
+      sensitive_pattern(/^snmp-server user .+auth \S+ (\S+)$/) { it[1] }
+      sensitive_pattern(/^snmp-server user .+priv \S+ (\S+)$/) { it[1] }
+      sensitive_pattern(/^username \S+ privilege \d+ (?:password|secret) (?:\d+ )?(\S+)/) { it[1] }
+      sensitive_pattern(/^username .+? password \d+\s+(\S+).*/) { it[1] }
+      sensitive_pattern(/^username .+? secret \d+\s+(\S+).*/) { it[1] }
+      sensitive_pattern(/^enable (?:password|secret) (?:\d )?\s*(\S+)/) { it[1] }
+      sensitive_pattern(/\s+(?:password|secret) (?:\d )?(\S+)/) { it[1] }
+      sensitive_pattern(/^tacacs-server key (?:\d )?(\S+)/) { it[1] }
+      sensitive_pattern(/^radius-server key (\S+)/) { it[1] }
+      sensitive_pattern(/^auth-mac (?:encrypted )?password (\S+)/) { it[1] }
+      sensitive_pattern(/^\s*ppp password (?:encrypted )?(.+)$/) { it[1] }
+      sensitive_pattern(/^\s*key-string (?:encrypted )?(.+)$/) { it[1] }
+      sensitive_pattern(/^\s+password (?:encrypted )?(.+)$/) { it[1] }
+      sensitive_pattern(/^\s+key (?:encrypted )?(.+)$/) { it[1] }
+      sensitive_pattern(/^\s+neighbor \S+ password (.+?)(?: encrypted)?$/) { it[1] }
+      sensitive_pattern(/^\s+ip ospf \S+ message-digest-key \d+ md5 (?:encrypted )?(.+)$/) { it[1] }
+      sensitive_pattern(/^\s+ip ospf \S+ authentication-key (?:encrypted )?(.+)$/) { it[1] }
+      sensitive_pattern(/^\s*aes-key (?:encrypted )?(.+)$/) { it[1] }
+
+      runbook :get do |book|
+        book.command('show system') do |result|
+          stable = result.output.each_line.grep_v(
+            /\A\s*\n\z
+            |System\ Status
+            |RAM\s*:
+            |Uptime\s*:
+            |Flash\s*:
+            |Current\ software\s*:
+            |Software\ version\s*:
+            |Build\ date\s*:
+            /x,
+          )
+          comment("-- show system #{'-' * 66}\n#{stable.join}#{'-' * 80}\n")
+        end
+        book.command('show running-config')
+      end
+
+      communication :telnet do |config|
+        config.username_prompt = /^login:\s/i
+        config.password_prompt = /^password:\s/i
+      end
+
+      communication :ssh, :telnet do |config|
+        config.post_login do |run|
+          if (enable = run.secret('enable'))
+            run.cli.write("enable\n")
+            run.cli.expect(/^Password:\s/)
+            run.cli.write("#{enable.value}\n")
+            run.cli.expect(run.cli.prompt)
+          else
+            run.cli.command('enable')
+          end
+        end
+        config.pre_logout { |run| run.cli.write("exit\n") }
+      end
+    end
+  end
+end