netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/storage/backup_lock.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    module Storage
+      # 路径锁在设备采集之前取得；锁文件长期保留，避免等待者落在已经删除的 inode 上。
+      class BackupLock
+        STORAGE_KEY = :net_connector_backup_delegation
+        private_constant :STORAGE_KEY
+
+        attr_reader :path
+
+        def self.lock_path(path)
+          destination = File.expand_path(path)
+          directory = File.realpath(File.dirname(destination))
+          # 锁名先折叠 Unicode 与大小写，避免大小写不敏感文件系统上的别名绕过互斥。
+          # 在区分大小写的文件系统上可能保守地合并两个锁，但不会改写目标文件名。
+          filename = File.basename(destination).b.force_encoding(Encoding::UTF_8)
+          filename = filename.valid_encoding? ? filename.unicode_normalize(:nfc).downcase(:fold).unicode_normalize(:nfc) : filename.b.downcase
+          File.join(directory, ".net-connector-#{Digest::SHA256.hexdigest(filename)}.lock")
+        end
+
+        def self.synchronize(path, **options, &) = new(path, **options).synchronize(&)
+
+        def initialize(path, timeout: 0, host: nil)
+          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+          unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout >= 0 && timeout.to_f.finite?
+            raise ArgumentError, "lock_timeout must be a nonnegative finite number"
+          end
+
+          @path = File.expand_path(path).freeze
+          @lock_path = self.class.lock_path(@path).freeze
+          @timeout, @host = timeout.to_f, host
+        end
+
+        def synchronize
+          # Fleet 只向下层备份借用一次；消费后清除，采集回调中的递归备份仍须竞争锁。
+          # Thread#[] 是 Fiber 局部存储；fork 后不能消费父进程的借用记录。
+          if Thread.current[STORAGE_KEY] == [@lock_path, Process.pid]
+            Thread.current[STORAGE_KEY] = nil
+            return yield self
+          end
+
+          file = nil
+          owned = false
+          begin
+            file = open_lock
+            verify_lock!(file)
+            acquire(file)
+            verify_lock!(file)
+            owned = true
+            @owner = [Process.pid, Fiber.current]
+            yield self
+          ensure
+            @owner = nil if owned
+            file&.close
+          end
+        end
+
+        # 仅持有实际 flock 的同一 Fiber 可授权一次内层采集，避免把路径锁变成任意可重入锁。
+        def with_delegated_lock
+          raise ThreadError, "backup path delegation requires lock ownership" unless @owner == [Process.pid, Fiber.current]
+
+          previous = Thread.current[STORAGE_KEY]
+          begin
+            Thread.current[STORAGE_KEY] = [@lock_path, Process.pid]
+            yield
+          ensure
+            Thread.current[STORAGE_KEY] = previous
+          end
+        end
+
+        private
+
+        def open_lock
+          File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600)
+        rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO
+          raise ArgumentError, "backup lock must be a private regular file", cause: nil
+        end
+
+        def verify_lock!(file)
+          stat = file.stat
+          unless stat.file? && stat.uid == Process.euid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise ArgumentError, "backup lock must be an owned regular file with mode 0600 and one link"
+          end
+          current = File.lstat(@lock_path)
+          unless current.file? && current.dev == stat.dev && current.ino == stat.ino
+            raise ArgumentError, "backup lock path changed while acquiring ownership"
+          end
+        rescue Errno::ENOENT
+          raise ArgumentError, "backup lock path changed while acquiring ownership", cause: nil
+        end
+
+        def acquire(file)
+          deadline = monotonic + @timeout
+          loop do
+            acquired = file.flock(File::LOCK_EX | File::LOCK_NB)
+            return if acquired && (@timeout.zero? || monotonic < deadline)
+
+            remaining = deadline - monotonic
+            if remaining <= 0
+              raise BackupBusy.new("backup path already belongs to another operation", host: @host, phase: :backup), cause: nil
+            end
+            wait([remaining, 0.05].min)
+          end
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        def wait(seconds) = sleep(seconds)
+      end
+    end
+  end
+end

data/lib/netstack/connector/storage/private_file.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "tempfile"
+
+module Netstack
+  module Connector
+    module Storage
+      # 文件同步和目录项同步分别记录；原子可见不等于断电后仍能恢复新目录项。
+      module PrivateFile
+        Receipt = Data.define(:path, :state, :phase) do
+          def initialize(path:, state:, phase:)
+            unless path.is_a?(String) && !path.empty? && %i[not_committed committed durable].include?(state) &&
+                   %i[resolve_parent temporary_file write file_sync rename directory_open directory_sync cleanup complete].include?(phase)
+              raise ArgumentError, "invalid file write receipt"
+            end
+            super(path: path.dup.freeze, state: state, phase: phase)
+          end
+
+          def committed? = state != :not_committed
+          def durable? = state == :durable
+        end
+
+        class WriteError < IOError
+          attr_reader :receipt, :code, :underlying_type
+
+          def initialize(receipt:, underlying_type:)
+            raise ArgumentError, "receipt must be a file write receipt" unless receipt.instance_of?(Receipt)
+
+            @receipt = receipt
+            @underlying_type = underlying_type.dup.freeze
+            @code, message = if receipt.durable?
+                               [:file_finalize_failed, "file replacement is durable; finalization failed"]
+                             elsif receipt.committed?
+                               [:file_persistence_unconfirmed, "file replacement is committed; durability is unconfirmed"]
+                             else
+                               [:file_write_failed, "file write failed before replacement was committed"]
+                             end
+            super(message)
+          end
+
+          def inspect = "#<#{self.class} state=#{receipt.state} phase=#{receipt.phase}>"
+        end
+
+        class PersistenceError < WriteError; end
+
+        class DirectorySyncUnsupported < WriteError
+          def initialize(**options)
+            super
+            @code = :directory_sync_unsupported
+          end
+
+          def message = "file replacement is committed; directory synchronization is unsupported"
+          alias to_s message
+        end
+
+        UNSUPPORTED_DIRECTORY_SYNC = [Errno::EINVAL, Errno::ENOSYS, Errno::ENOTSUP, Errno::EOPNOTSUPP,
+                                      NotImplementedError].uniq.freeze
+        private_constant :UNSUPPORTED_DIRECTORY_SYNC
+
+        # 外部子类可重写消息或回执；只有本写入器定义的具体错误类型可提供完成事实。
+        def self.receipt_error?(error)
+          [WriteError, PersistenceError, DirectorySyncUnsupported].any? { |type| error.instance_of?(type) }
+        end
+
+        # 统一返回写入回执；失败时从异常 receipt 判断目录项是否已经替换。
+        def self.write(path, contents)
+          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+
+          receipt = Receipt.new(path: File.expand_path(path), state: :not_committed, phase: :resolve_parent)
+          directory = File.realpath(File.dirname(receipt.path))
+          destination = File.join(directory, File.basename(receipt.path))
+          receipt = receipt.with(phase: :temporary_file)
+          Tempfile.create([".net-connector-", ".tmp"], directory) do |file|
+            file.binmode
+            file.chmod(0o600)
+            receipt = receipt.with(phase: :write)
+            file.write(contents)
+            receipt = receipt.with(phase: :file_sync)
+            file.flush
+            file.fsync
+            receipt = receipt.with(phase: :rename)
+            File.rename(file.path, destination)
+            receipt = receipt.with(state: :committed, phase: :directory_open)
+            File.open(directory, File::RDONLY | File::NOFOLLOW) do |parent|
+              raise IOError, "parent is not a directory" unless parent.stat.directory?
+
+              receipt = receipt.with(phase: :directory_sync)
+              parent.fsync
+              receipt = receipt.with(state: :durable, phase: :cleanup)
+            end
+          end
+          receipt.with(phase: :complete)
+        rescue StandardError, NotImplementedError => error
+          raise unless receipt
+
+          unsupported = receipt.phase == :directory_sync && UNSUPPORTED_DIRECTORY_SYNC.any? { |type| error.is_a?(type) }
+          klass = if unsupported
+                    DirectorySyncUnsupported
+                  elsif receipt.committed?
+                    PersistenceError
+                  else
+                    WriteError
+                  end
+          raise klass.new(receipt: receipt, underlying_type: error.class.name.to_s), cause: nil
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/storage/safe_file.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    module Storage
+      # 对同一 FD 做类型检查和读取；NOFOLLOW 只保护最后一个路径分量，目录由调用方保护。
+      module SafeFile
+        Fingerprint = Data.define(:path, :sha256, :mode, :dev, :ino)
+
+        def self.open(path, missing: false, replace_symlink: false)
+          file = open_handle(path, missing: missing, replace_symlink: replace_symlink)
+          return nil unless file
+
+          begin
+            stat = file.stat
+            raise ArgumentError, "saved configuration is not a regular file" unless stat.file?
+
+            file.binmode
+            yield file, stat
+          ensure
+            file.close
+          end
+        end
+
+        def self.fingerprint(path, **options)
+          self.open(path, **options) { |file, stat| fingerprint_io(path, file, stat) }
+        end
+
+        def self.fingerprint_io(path, file, stat)
+          digest = Digest::SHA256.new
+          while (chunk = file.read(64 * 1024))
+            digest << chunk
+          end
+          Fingerprint.new(path: path.dup.freeze, sha256: digest.hexdigest.freeze,
+                          mode: stat.mode & 0o7777, dev: stat.dev, ino: stat.ino)
+        end
+
+        # 未变内容可保留 mtime，但不能把已替换的目录项误认成刚读取的旧文件。
+        def self.same_entry?(path, fingerprint)
+          stat = File.lstat(path)
+          stat.file? && stat.dev == fingerprint.dev && stat.ino == fingerprint.ino
+        rescue Errno::ENOENT
+          false
+        end
+
+        def self.open_handle(path, missing:, replace_symlink:)
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+        rescue Errno::ENOENT
+          raise unless missing
+        rescue Errno::ELOOP
+          raise ArgumentError, "saved configuration is not a regular file", cause: nil unless replace_symlink
+        rescue Errno::ENXIO
+          raise ArgumentError, "saved configuration is not a regular file", cause: nil
+        end
+
+        private_class_method :open_handle
+      end
+    end
+  end
+end

data/lib/netstack/connector/storage/saved_config.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "fileutils"
+require "ipaddr"
+
+module Netstack
+  module Connector
+    module Storage
+      # 直接导出已有本地配置，无需访问清单服务。
+      class SavedConfig
+        # 只用规范化的管理地址标识配置，避免设备改名改变备份身份。
+        def self.filename(host)
+          raise ArgumentError, "host must be an IP address" unless host.is_a?(String) && !host.include?("/")
+
+          "#{IPAddr.new(host).to_s.tr(":", "_")}.txt"
+        rescue IPAddr::Error
+          raise ArgumentError, "host must be an IP address"
+        end
+
+        # 只读取规范设备地址对应的文件，不维护第二套历史文件命名。
+        def initialize(directory:)
+          raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+
+          @directory = File.expand_path(directory).freeze
+        end
+
+        # 从同一已验证文件描述符取得路径或内容。
+        def find(host, required: true)
+          with_file(host, required: required) { |path, _file, _stat| path }
+        end
+
+        # 比较基线也从经过 fstat 的同一 FD 读取，不在 find 后重新按路径打开。
+        def fingerprint(host, required: true)
+          with_file(host, required: required) { |path, file, stat| SafeFile.fingerprint_io(path, file, stat) }
+        end
+
+        def read(host)
+          with_file(host) { |_path, file, _stat| file.read }
+        end
+
+        def with_file(host, required: true)
+          path = File.join(@directory, self.class.filename(host))
+          SafeFile.open(path, missing: !required) { |file, stat| yield path, file, stat }
+        end
+
+        private :with_file
+
+        # 将已保存配置写入目标文件或标准输出。
+        def export(host:, output: nil, io: $stdout)
+          contents = read(host)
+          if output
+            raise ArgumentError, "output must be a nonempty String" unless output.is_a?(String) && !output.empty?
+
+            destination = File.expand_path(output)
+            directory = File.dirname(destination)
+            FileUtils.mkdir_p(directory, mode: 0o700)
+            PrivateFile.write(destination, contents).path
+          else
+            io.binmode if io.respond_to?(:binmode)
+            io.write(contents)
+            nil
+          end
+        end
+
+        # 使用指定模板解析已有配置，无需访问设备或清单服务。
+        def parse(host:, template:, template_dir: nil)
+
+          parser = TextFSM.new(template_dir: template_dir)
+          parser.call(read(host), template: template, host: host)
+        end
+      end
+    end
+  end
+end

data/lib/netstack/connector/terminal_renderer.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "stringio"
+
+module Netstack
+  module Connector
+    # 把终端编辑控制符渲染成可读、兼容 UTF-8 和二进制的逐行日志。
+    class TerminalRenderer
+      # 将字节流完整渲染为字符串，供测试和一次性转换使用。
+      def self.render(input, strict_utf8: false)
+        output = StringIO.new("".b)
+        renderer = new(output, strict_utf8: strict_utf8)
+        renderer.write(input)
+        renderer.finish
+        output.string
+      end
+
+      # 初始化当前行、光标和转义序列状态。
+      def initialize(target, max_line_bytes: 32 * 1024 * 1024, strict_utf8: false)
+        raise ArgumentError, "target must respond to write" unless target.respond_to?(:write)
+        unless max_line_bytes.is_a?(Integer) && max_line_bytes.positive?
+          raise ArgumentError, "max_line_bytes must be positive"
+        end
+        raise ArgumentError, "strict_utf8 must be true or false" unless [true, false].include?(strict_utf8)
+
+        @target = target
+        @line = "".b
+        @cursor = 0
+        @escape_state = nil
+        @csi_parameters = "".b
+        @max_line_bytes = max_line_bytes
+        @strict_utf8 = strict_utf8
+      end
+
+      # 普通文本成段写入；控制序列仍逐字节解析，保留跨分片状态。
+      def write(input)
+        bytes = input.to_s.b
+        offset = 0
+        while offset < bytes.bytesize
+          byte = bytes.getbyte(offset)
+          if @escape_state || (byte < 32 && byte != 9)
+            consume(byte)
+            offset += 1
+          else
+            boundary = bytes.index(/[\x00-\x08\x0a-\x1f]/n, offset) || bytes.bytesize
+            write_text(bytes.byteslice(offset, boundary - offset))
+            offset = boundary
+          end
+        end
+        bytes.bytesize
+      end
+
+      # 刷新底层日志目标。
+      def flush
+        @target.flush if @target.respond_to?(:flush)
+      end
+
+      # 写出尚未换行的尾行并刷新目标。
+      def finish
+        emit_line(newline: false) unless @line.empty?
+        flush
+      end
+
+      private
+
+      # 处理普通控制字符、换行、回车和转义序列起始符。
+      def consume(byte)
+        return consume_escape(byte) if @escape_state
+
+        case byte
+        when 7 then nil
+        when 8 then @cursor = [@cursor - 1, 0].max
+        when 10 then emit_line(newline: true)
+        when 13 then @cursor = 0
+        when 27 then @escape_state = :escape
+        else write_byte(byte) if byte == 9 || byte >= 32
+        end
+      end
+
+      # 根据转义序列阶段继续解析终端控制字节。
+      def consume_escape(byte)
+        case @escape_state
+        when :escape
+          start_escape_sequence(byte)
+        when :csi
+          finish_csi(byte)
+        when :osc
+          @escape_state = nil if byte == 7
+          @escape_state = :osc_escape if byte == 27
+        when :osc_escape
+          @escape_state = (byte == 92) ? nil : :osc
+        end
+      end
+
+      # 识别 CSI 或 OSC 序列，并忽略未知的单字节序列。
+      def start_escape_sequence(byte)
+        case byte
+        when 91
+          @csi_parameters.clear
+          @escape_state = :csi
+        when 93 then @escape_state = :osc
+        else
+          @escape_state = nil
+        end
+      end
+
+      # 收集 CSI 参数并在终止字节到达时执行光标操作。
+      def finish_csi(byte)
+        if byte.between?(0x40, 0x7e)
+          apply_csi(byte)
+          @escape_state = nil
+        elsif byte.between?(0x20, 0x3f)
+          raise OutputLimitExceeded, "terminal escape sequence is too long" if @csi_parameters.bytesize >= 64
+
+          @csi_parameters << byte
+        else
+          @escape_state = nil
+        end
+      end
+
+      # 应用有限范围内的光标移动和整行擦除控制。
+      def apply_csi(command)
+        count = Integer(@csi_parameters[/\d+/, 0] || "1", 10)
+        case command
+        when 67 then @cursor += count
+        when 68 then @cursor = [@cursor - count, 0].max
+        when 71 then @cursor = [count - 1, 0].max
+        when 75 then erase_line(Integer(@csi_parameters[/\d+/, 0] || "0", 10))
+        end
+      end
+
+      # 按终端擦除模式修改当前行缓冲区。
+      def erase_line(mode)
+        case mode
+        when 0 then @line = @line.byteslice(0, @cursor)
+        when 1
+          @line = (" ".b * [@cursor + 1, @line.bytesize].min) + @line.byteslice((@cursor + 1)..).to_s
+        when 2
+          @line.clear
+          @cursor = 0
+        end
+      end
+
+      # 在光标位置写入字节，并限制单行缓冲大小。
+      def write_byte(byte)
+        raise OutputLimitExceeded, "terminal line exceeded max_line_bytes" if @cursor >= @max_line_bytes
+
+        @line << (" " * (@cursor - @line.bytesize)) if @cursor > @line.bytesize
+        (@cursor < @line.bytesize) ? @line.setbyte(@cursor, byte) : @line << byte
+        @cursor += 1
+      end
+
+      # 只合并无控制符的字节；超限时沿用逐字节路径，保留失败前已接受的前缀。
+      def write_text(text)
+        return text.each_byte { |byte| write_byte(byte) } if @cursor + text.bytesize > @max_line_bytes
+
+        @line << (" " * (@cursor - @line.bytesize)) if @cursor > @line.bytesize
+        if @cursor == @line.bytesize
+          @line << text
+        else
+          @line[@cursor, text.bytesize] = text
+        end
+        @cursor += text.bytesize
+      end
+
+      # 删除行尾空白，写出当前行并重置光标。
+      def emit_line(newline:)
+        @target.write(utf8_safe(@line.sub(/[ \t]+\z/n, "")))
+        @target.write("\n") if newline
+        @line.clear
+        @cursor = 0
+      end
+
+      # 日志把非法字节转义；解析必须拒绝终端编辑产生的损坏字节，不能制造可写业务证据。
+      def utf8_safe(line)
+        text = line.dup.force_encoding(Encoding::UTF_8)
+        return text.b if text.valid_encoding?
+        raise Encoding::InvalidByteSequenceError, "terminal editing produced invalid UTF-8" if @strict_utf8
+
+        text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join }.b
+      end
+    end
+  end
+end

data/lib/netstack/connector/terminal_text.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 设备/文件提供的是字节，不受 Ruby 源文件编码控制。解析边界只接受 UTF-8，
+    # 不猜测编码、不改写原文，也不让终端编辑把非法字节抹掉后变成可信证据。
+    module TerminalText
+      def self.utf8(bytes, host: nil)
+        raise ArgumentError, "text must be a String" unless bytes.is_a?(String)
+
+        text = bytes.b.force_encoding(Encoding::UTF_8)
+        invalid_encoding!(host) unless text.valid_encoding?
+        text
+      end
+
+      def self.render(bytes, host: nil)
+        TerminalRenderer.render(utf8(bytes, host: host), strict_utf8: true).force_encoding(Encoding::UTF_8)
+      rescue Encoding::InvalidByteSequenceError
+        invalid_encoding!(host)
+      end
+
+      def self.invalid_encoding!(host)
+        raise ParsingError.new("device output is not valid UTF-8", code: :invalid_output_encoding,
+                               host: host, phase: :parse), cause: nil
+      end
+
+      private_class_method :invalid_encoding!
+    end
+  end
+end

data/lib/netstack/connector/textfsm.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 将设备命令回显或配置文本按 TextFSM 模板转换为结构化记录。
+    class TextFSM
+      # 设备入口与功能实现共置，Device 只组合能力，不重复业务流程。
+      module Capability
+        # 执行命令并按厂商、命令或显式 TextFSM 模板返回结构化记录。
+        def parse_command(command, template: nil, template_dir: nil)
+          parser = TextFSM.new(template_dir: template_dir)
+          parser.call(execute_command(command).value!, template: template, vendor: vendor, command: command, host: host)
+        end
+
+        # 采集运行配置并使用指定 TextFSM 模板提取结构化记录。
+        def parse_config(template:, template_dir: nil)
+          parser = TextFSM.new(template_dir: template_dir)
+          parser.call(running_config.value!, template: template, host: host)
+        end
+      end
+
+      DEFAULT_TEMPLATE_DIR = File.expand_path("../../../resources/textfsm", __dir__).freeze
+
+      # 配置模板目录和 Netmiko 风格的命令索引文件。
+      def initialize(template_dir: nil, index: "index")
+        template_dir ||= DEFAULT_TEMPLATE_DIR
+        raise ArgumentError, "template_dir must be a nonempty String" unless template_dir.is_a?(String) && !template_dir.empty?
+        raise ArgumentError, "index must be a nonempty String" unless index.is_a?(String) && !index.empty?
+
+        @template_dir = File.expand_path(template_dir)
+        @index = index
+      end
+
+      # 显式模板按路径读取；未指定时按厂商和命令从索引选择模板。
+      def call(text, template: nil, vendor: nil, command: nil, host: nil)
+        require "textfsm"
+
+        text = TerminalText.render(text, host: host)
+        if template
+          raise ArgumentError, "template must be a nonempty String" unless template.is_a?(String) && !template.empty?
+
+          ::TextFSM::Parser.from_file(File.expand_path(template, @template_dir)).parse_hashes(text)
+        else
+          raise ArgumentError, "vendor and command are required for template lookup" unless vendor && command.is_a?(String) && !command.empty?
+
+          attributes = { "Vendor" => vendor.to_s, "Command" => command }
+          table = ::TextFSM::CliTable.new(index: @index, template_dir: @template_dir)
+          unless table.index.match(attributes)
+            raise ParsingError.new("no TextFSM template matches this vendor and command",
+                                   code: :template_missing, host: host, phase: :parse)
+          end
+          table.parse(text, attributes: attributes).to_hashes
+        end
+      rescue ::TextFSM::IndexError
+        raise ParsingError.new("TextFSM template index is invalid",
+                               code: :template_invalid, host: host, phase: :parse), cause: nil
+      rescue ::TextFSM::TemplateError
+        raise ParsingError.new("TextFSM template is invalid",
+                               code: :template_invalid, host: host, phase: :parse), cause: nil
+      rescue ::TextFSM::ParseError
+        raise ParsingError.new("TextFSM could not parse the device output",
+                               code: :parse_failed, host: host, phase: :parse), cause: nil
+      rescue IOError, SystemCallError
+        raise ParsingError.new("unable to read TextFSM template",
+                               code: :template_unreadable, host: host, phase: :parse), cause: nil
+      end
+    end
+  end
+end