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.



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

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.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

def api_version
  @api_version
end

#config ⇒ Object (readonly)

Returns the value of attribute config.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

def config
  @config
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

def id
  @id
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

def logger
  @logger
end

#source_path ⇒ Object (readonly)

Returns the value of attribute source_path.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

def source_path
  @source_path
end

#storage ⇒ Object (readonly)

Returns the value of attribute storage.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

def storage
  @storage
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



137
138
139
 
# File 'lib/kward/plugins/host.rb', line 137

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.



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

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:



155
156
157
 
# File 'lib/kward/plugins/host.rb', line 155

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

#codex_responses ⇒ Object

Streams Responses-shaped events through Kward's normal Codex provider client without exposing the configured credentials to plugin code.



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

def codex_responses
  @codex_responses ||= PluginCodexResponses.new
end

#http_server(host: "127.0.0.1", port: 0, max_body_bytes: PluginHTTPServer::DEFAULT_MAX_BODY_BYTES, request_timeout: PluginHTTPServer::DEFAULT_REQUEST_TIMEOUT, max_clients: 8, &handler) ⇒ Object

Creates a loopback-only HTTP listener owned by this plugin. The listener is stopped automatically during plugin reload or shutdown.



167
168
169
170
171
 
# File 'lib/kward/plugins/host.rb', line 167

def http_server(host: "127.0.0.1", port: 0, max_body_bytes: PluginHTTPServer::DEFAULT_MAX_BODY_BYTES, request_timeout: PluginHTTPServer::DEFAULT_REQUEST_TIMEOUT, max_clients: 8, &handler)
  server = PluginHTTPServer.new(host: host, port: port, max_body_bytes: max_body_bytes, request_timeout: request_timeout, max_clients: max_clients, &handler)
  on_cleanup(server) { |resource| resource.stop }
  server
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:



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

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.



200
201
202
203
204
205
206
 
# File 'lib/kward/plugins/host.rb', line 200

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.



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

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.



209
210
211
 
# File 'lib/kward/plugins/host.rb', line 209

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