Class: Immunio::Plugin

Inherits:
Object
  • Object
show all
Defined in:
lib/immunio/plugin.rb

Overview

Holds the status of a plugin.

A plugin can have one of four statuses:

  • pending: initial state, waiting to be loaded

  • loaded: successfully loaded

  • failed: error while loading

  • disabled: disabled in config, will never be loaded

Each registered plugin is reported to the backend via the ‘EnvironmentReporter`.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, hooks = []) ⇒ Plugin

Returns a new instance of Plugin.



19
20
21
22
23
24
 
# File 'lib/immunio/plugin.rb', line 19

def initialize(name, hooks = [])
  @name = name
  @status = 'pending'
  @version = nil
  @hooks = hooks
end

Instance Attribute Details

#hooks ⇒ Object

Returns the value of attribute hooks.



17
18
19
 
# File 'lib/immunio/plugin.rb', line 17

def hooks
  @hooks
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



15
16
17
 
# File 'lib/immunio/plugin.rb', line 15

def status
  @status
end

#version ⇒ Object

Returns the value of attribute version.



16
17
18
 
# File 'lib/immunio/plugin.rb', line 16

def version
  @version
end

Class Method Details

.load(name, options = {}) ⇒ Object

DSL to register a plugin, its status and version.

A ‘feature` name can be passed to determine if the plugin should be enabled. If the plugin is disabled, the block will not run.

You MUST explicitly call ‘plugin.loaded!` in the block to indicate that the plugin was loaded successfully, or else it will be kept as ’pending’.

Eg.:

Immunio::Plugin.load 'SomePluginName', feature: 'xss' do |plugin|
  if defined? SomePlugin
    # Your loading code here ...
    plugin.loaded! SomePluginName::VERSION
  end
end



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/immunio/plugin.rb', line 75

def self.load(name, options = {})
  if options.key? :feature
    enabled = Immunio.agent.plugin_enabled?(options[:feature])
  else
    enabled = true
  end

  plugin = registered[name] = new(name, options.fetch(:hooks, []))

  unless enabled # plugin is disabled
    plugin.disabled!
    return
  end

  Immunio.logger.debug "Loading plugin #{name} ..."
  begin
    yield plugin
  rescue StandardError, LoadError => e
    plugin.failed! e
  end
end

.registered ⇒ Object 



54
55
56
 
# File 'lib/immunio/plugin.rb', line 54

def self.registered
  @registered ||= {}
end

Instance Method Details

#disabled! ⇒ Object 



32
33
34
35
 
# File 'lib/immunio/plugin.rb', line 32

def disabled!
  @status = 'disabled'
  Immunio.logger.debug "Plugin #{@name} is disabled"
end

#failed!(error) ⇒ Object 



37
38
39
40
 
# File 'lib/immunio/plugin.rb', line 37

def failed!(error)
  @status = 'failed'
  Immunio.logger.error "Plugin #{@name} failed to load: #{error}"
end

#inspect ⇒ Object 



42
43
44
 
# File 'lib/immunio/plugin.rb', line 42

def inspect
  "<#{self.class} name=#{@name.inspect} status=#{@status.inspect} version=#{@version.inspect} hooks=#{@hooks.inspect}>"
end

#loaded!(version) ⇒ Object 



26
27
28
29
30
 
# File 'lib/immunio/plugin.rb', line 26

def loaded!(version)
  @status = 'loaded'
  @version = version
  Immunio.logger.debug "Plugin #{@name} v#{version} loaded successfully"
end

#to_msgpack(packer) ⇒ Object 



46
47
48
49
50
51
52
 
# File 'lib/immunio/plugin.rb', line 46

def to_msgpack(packer)
  packer.write_map_header 3
  # `name` is provided as the key in `registered`
  packer.write('status').write(@status)
  packer.write('version').write(@version)
  packer.write('hooks').write(@hooks)
end