Skip to content
Kward Search API index

Class: Kward::PluginHost

Inherits:
Object
  • Object
show all
Defined in:
lib/kward/plugins/host.rb

Overview

Shared immutable metadata and managed services for one identified plugin.

Constant Summary collapse

ID_PATTERN = 
/\A[A-Za-z0-9][A-Za-z0-9._-]*\z/.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:, version:, api_version:, source_path: nil, config: nil, storage: nil, logger: nil, env: ENV, storage_root: ConfigFiles.config_dir, warning_sink: nil) ⇒ PluginHost

Returns a new instance of PluginHost.



137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/kward/plugins/host.rb', line 137

def initialize(id:, version:, api_version:, source_path: nil, config: nil, storage: nil, logger: nil, env: ENV, storage_root: ConfigFiles.config_dir, warning_sink: nil)
  @id = validate_id(id).freeze
  @version = validate_value(version, "plugin version").freeze
  @api_version = validate_value(api_version, "plugin API version").freeze
  @source_path = source_path&.to_s&.freeze
  @config = freeze_config(config.nil? ? configured_values : config)
  @storage = storage || PluginStore.new(@id, root: storage_root)
  @logger = logger || default_logger
  @env = env
  @resources = PluginResources.new(name: "Kward plugin #{id}", warning_sink: warning_sink)
end

Instance Attribute Details

#api_version ⇒ Object (readonly)

Returns the value of attribute api_version.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def api_version
  @api_version
end

#config ⇒ Object (readonly)

Returns the value of attribute config.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def config
  @config
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def id
  @id
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def logger
  @logger
end

#source_path ⇒ Object (readonly)

Returns the value of attribute source_path.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def source_path
  @source_path
end

#storage ⇒ Object (readonly)

Returns the value of attribute storage.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def storage
  @storage
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



135
136
137
 
# File 'lib/kward/plugins/host.rb', line 135

def version
  @version
end

Instance Method Details

#activate! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Activates managed runtime services after plugin loading completes.



170
171
172
173
 
# File 'lib/kward/plugins/host.rb', line 170

def activate!
  @resources.activate!
  self
end

#background(name: nil, cancellation: nil, &block) ⇒ PluginTask

Starts cooperative background work owned by this plugin. The block may accept a cancellation token and must stop cooperatively when cancelled.

Returns:



153
154
155
 
# File 'lib/kward/plugins/host.rb', line 153

def background(name: nil, cancellation: nil, &block)
  @resources.background(name: name, cancellation: cancellation, &block)
end

#on_cleanup(resource = nil, &block) ⇒ PluginDisposable Also known as: manage

Registers idempotent cleanup for a subscription or other plugin resource. The returned disposable may be invoked early; otherwise Kward invokes it during plugin reload or shutdown.

Returns:



162
163
164
 
# File 'lib/kward/plugins/host.rb', line 162

def on_cleanup(resource = nil, &block)
  @resources.on_cleanup(resource, &block)
end

#secret(key, env: nil) ⇒ Object

Reads a secret from private plugin config, an explicit environment variable, or the plugin's conventional KWARD_PLUGIN_* variable.



184
185
186
187
188
189
190
 
# File 'lib/kward/plugins/host.rb', line 184

def secret(key, env: nil)
  key = validate_value(key, "secret key")
  value = config[key]
  value = @env[env.to_s] if value.nil? && env
  value = @env[default_secret_env_name(key)] if value.nil?
  value.to_s unless value.nil?
end

#shutdown(timeout: PluginResources::DEFAULT_SHUTDOWN_TIMEOUT) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Cancels background work and invokes registered cleanup callbacks.



177
178
179
180
 
# File 'lib/kward/plugins/host.rb', line 177

def shutdown(timeout: PluginResources::DEFAULT_SHUTDOWN_TIMEOUT)
  @resources.shutdown(timeout: timeout)
  self
end

#to_h ⇒ Object

Returns public metadata suitable for diagnostics and capability reports.



193
194
195
 
# File 'lib/kward/plugins/host.rb', line 193

def to_h
  { id: id, version: version, api_version: api_version }.freeze
end