Class: Cuboid::Application

Inherits:
Object show all
Includes:
Support::Mixins::Observable, Support::Mixins::Parts, Support::Mixins::SpecInstances, UI::Output, Utilities, Singleton
Defined in:
lib/cuboid/application.rb,
lib/cuboid/application/runtime.rb,
lib/cuboid/application/parts/data.rb,
lib/cuboid/application/parts/state.rb,
lib/cuboid/application/parts/report.rb

Overview

Author:

  • Tasos “Zapotek” Laskos <tasos.laskos@gmail.com>

Defined Under Namespace

Modules: Parts, PrependMethods Classes: Error, Runtime

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Support::Mixins::Parts

included

Methods included from Support::Mixins::Observable

included

Methods included from Utilities

#available_port, available_port_mutex, #bytes_to_kilobytes, #bytes_to_megabytes, #caller_name, #caller_path, #exception_jail, #generate_token, #hms_to_seconds, #port_available?, #rand_port, #random_seed, #regexp_array_match, #remove_constants, #seconds_to_hms

Methods included from UI::Output

#error_buffer, initialize, #log_error, #output_provider_file, #print_bad, #print_debug, #print_error, #print_info, #print_line, #print_ok, #print_status, #print_verbose, #reroute_to_file, #reroute_to_file?

Methods included from UI::OutputInterface

initialize

Methods included from UI::OutputInterface::Personalization

#included

Methods included from UI::OutputInterface::Controls

#debug?, #debug_level, #debug_level_1?, #debug_level_2?, #debug_level_3?, #debug_level_4?, #debug_off, #debug_on, initialize, #verbose?, #verbose_off, #verbose_on

Methods included from UI::OutputInterface::ErrorLogging

#error_logfile, #has_error_log?, initialize, #set_error_logfile

Methods included from UI::OutputInterface::Implemented

#print_debug_backtrace, #print_debug_exception, #print_debug_level_1, #print_debug_level_2, #print_debug_level_3, #print_debug_level_4, #print_error_backtrace, #print_exception

Methods included from UI::OutputInterface::Abstract

#output_provider_file, #print_bad, #print_debug, #print_error, #print_info, #print_line, #print_ok, #print_status, #print_verbose

Methods included from Support::Mixins::SpecInstances

prepended

Constructor Details

#initialize ⇒ Application

Returns a new instance of Application.



344
345
346
347
348
 
# File 'lib/cuboid/application.rb', line 344

def initialize
    super

    @runtime = Runtime.new
end

Class Method Details

._spec_instance_cleanup(i) ⇒ Object 



387
388
389
390
 
# File 'lib/cuboid/application.rb', line 387

def self._spec_instance_cleanup( i )
    # i.clean_up
    i.reset
end

.agent_service_for(name, service) ⇒ Object 



210
211
212
 
# File 'lib/cuboid/application.rb', line 210

def agent_service_for( name, service )
    agent_services[name] = service
end

.agent_services ⇒ Object 



214
215
216
 
# File 'lib/cuboid/application.rb', line 214

def agent_services
    @agent_services ||= {}
end

.application ⇒ Object 



304
305
306
 
# File 'lib/cuboid/application.rb', line 304

def application
    @application
end

.application=(app) ⇒ Object 



308
309
310
 
# File 'lib/cuboid/application.rb', line 308

def application=( app )
    @application = app
end

.connect(info) ⇒ Object 



292
293
294
295
 
# File 'lib/cuboid/application.rb', line 292

def connect( info )
    info = info.my_symbolize_keys
    Processes::Instances.connect( info[:url], info[:token] )
end

.handler_for(signal, handler) ⇒ Object 



218
219
220
 
# File 'lib/cuboid/application.rb', line 218

def handler_for( signal, handler )
    signal_handlers[signal] = handler
end

.inherited(application) ⇒ Object 



297
298
299
300
301
302
 
# File 'lib/cuboid/application.rb', line 297

def inherited( application )
    super

    application.prepend PrependMethods
    self.application = application
end

.instance_service_for(name, service) ⇒ Object 



119
120
121
 
# File 'lib/cuboid/application.rb', line 119

def instance_service_for( name, service )
    instance_services[name] = service
end

.instance_services ⇒ Object 



123
124
125
 
# File 'lib/cuboid/application.rb', line 123

def instance_services
    @instance_services ||= {}
end

.max_cores ⇒ Object 



99
100
101
 
# File 'lib/cuboid/application.rb', line 99

def max_cores
    @max_cores ||= 0
end

.max_disk ⇒ Object 



115
116
117
 
# File 'lib/cuboid/application.rb', line 115

def max_disk
    @max_disk ||= 0
end

.max_memory ⇒ Object 



107
108
109
 
# File 'lib/cuboid/application.rb', line 107

def max_memory
    @max_memory ||= 0
end

.mcp_app_tool(tool_class) ⇒ Object

Register an ‘MCP::Tool` subclass to ship at the top-level `/mcp` endpoint, alongside `CoreTools` (`list_instances`, `spawn_instance`, `kill_instance`) — i.e. NOT routed through the per-instance dispatcher and not requiring an `instance_id` argument. Use this for app-level catalog / metadata tools the client may want to consult before spawning anything.

Example:

class MyApp < Cuboid::Application
    mcp_app_tool ListChecks
end



186
187
188
 
# File 'lib/cuboid/application.rb', line 186

def mcp_app_tool( tool_class )
    mcp_app_tools << tool_class
end

.mcp_app_tools ⇒ Object 



190
191
192
 
# File 'lib/cuboid/application.rb', line 190

def mcp_app_tools
    @mcp_app_tools ||= []
end

.mcp_auth_validator ⇒ Object 



206
207
208
 
# File 'lib/cuboid/application.rb', line 206

def mcp_auth_validator
    @mcp_auth_validator
end

.mcp_authenticate_with(&block) ⇒ Object

Register a bearer-token validator for the MCP transport. The block receives the token string and should return a truthy principal (typically a User record) on success or nil/false on failure. See Cuboid::MCP::Auth for the request flow.

Without a registered validator the auth middleware passes every request through — keeps smoke tests / pre-auth-layer deployments simple.



202
203
204
 
# File 'lib/cuboid/application.rb', line 202

def mcp_authenticate_with( &block )
    @mcp_auth_validator = block
end

.mcp_service_for(name, handler) ⇒ Object

Register an MCP service handler. Mirrors ‘rest_service_for`: the application gem provides a module/class that exposes a set of tools and Cuboid::MCP::Server mounts them per-instance at `/instances/:instance/<name>` (just like REST mounts rest_service handlers at `/instances/:instance/<name>`).

The handler must respond to ‘.tools`, returning an Array of `MCP::Tool` subclasses. Each tool’s ‘call` receives a `server_context:` Hash containing at least `:instance` —the resolved RPC client for the engine instance the request is targeting.

Example:

module MyApp::MCPHandler
    class Ping < ::MCP::Tool
        tool_name 'ping'
        description 'Ping the application instance.'
        def self.call(server_context:, **)
            server_context[:instance].some_application_method
            ::MCP::Tool::Response.new([{ type: 'text', text: 'pong' }])
        end
    end
    TOOLS = [Ping].freeze
    def self.tools; TOOLS; end
end

class MyApp < Cuboid::Application
    mcp_service_for :my_service, MCPHandler
end



165
166
167
 
# File 'lib/cuboid/application.rb', line 165

def mcp_service_for( name, handler )
    mcp_services[name] = handler
end

.mcp_services ⇒ Object 



169
170
171
 
# File 'lib/cuboid/application.rb', line 169

def mcp_services
    @mcp_services ||= {}
end

.method_missing(sym, *args, &block) ⇒ Object 



312
313
314
315
316
317
318
 
# File 'lib/cuboid/application.rb', line 312

def method_missing( sym, *args, &block )
    if instance.respond_to?( sym )
        instance.send( sym, *args, &block )
    else
        super( sym, *args, &block )
    end
end

.provision_cores(cores) ⇒ Object 



95
96
97
 
# File 'lib/cuboid/application.rb', line 95

def provision_cores( cores )
    @max_cores = cores
end

.provision_disk(disk) ⇒ Object 



111
112
113
 
# File 'lib/cuboid/application.rb', line 111

def provision_disk( disk )
    @max_disk = disk
end

.provision_memory(ram) ⇒ Object 



103
104
105
 
# File 'lib/cuboid/application.rb', line 103

def provision_memory( ram )
    @max_memory = ram
end

.respond_to?(*args) ⇒ Boolean

Returns:

  • (Boolean) 


320
321
322
 
# File 'lib/cuboid/application.rb', line 320

def respond_to?( *args )
    super || instance.respond_to?( *args )
end

.rest_service_for(name, service) ⇒ Object 



127
128
129
 
# File 'lib/cuboid/application.rb', line 127

def rest_service_for( name, service )
    rest_services[name] = service
end

.rest_services ⇒ Object 



131
132
133
 
# File 'lib/cuboid/application.rb', line 131

def rest_services
    @rest_services ||= {}
end

.serialize_with(serializer) ⇒ Object 



226
227
228
 
# File 'lib/cuboid/application.rb', line 226

def serialize_with( serializer)
    @serializer = serializer
end

.serializer ⇒ Object 



230
231
232
233
234
235
 
# File 'lib/cuboid/application.rb', line 230

def serializer
    @serializer ||= nil

    # Default to JSON for REST API compatibility.
    @serializer || JSON
end

.signal_handlers ⇒ Object 



222
223
224
 
# File 'lib/cuboid/application.rb', line 222

def signal_handlers
    @signal_handlers ||= {}
end

.source_location ⇒ Object 



250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/cuboid/application.rb', line 250

def source_location
    splits = self.to_s.split ( '::' )
    app    = splits.pop

    last_const = Object
    splits.each do |const_name|
        last_const = last_const.const_get( const_name.to_sym )
    end

    File.expand_path last_const.const_source_location( app.to_sym ).first
end

.spawn(type, options = {}, &block) ⇒ Object 



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/cuboid/application.rb', line 262

def spawn( type, options = {}, &block )
    const = nil

    case type
    when :instance
        const = :Instances
    when :agent
        const = :Agents
    when :scheduler
        const = :Schedulers
    when :rest
        return Processes::Manager.spawn(
            :rest_service,
            options.merge( options: { paths: { application: source_location } } ),
            &block
        )
    when :mcp
        return Processes::Manager.spawn(
            :mcp,
            options.merge( options: { paths: { application: source_location } } ),
            &block
        )
    end

    Processes.const_get( const ).spawn(
      options.merge( application: source_location ),
      &block
    )
end

.valid_options?(options) ⇒ Boolean

Returns:

  • (Boolean) 


241
242
243
244
245
246
247
248
 
# File 'lib/cuboid/application.rb', line 241

def valid_options?( options )
    @validate_options_with ||= nil
    if @validate_options_with
        return instance.method( @validate_options_with ).call( options )
    end

    true
end

.validate_options_with(handler) ⇒ Object 



237
238
239
 
# File 'lib/cuboid/application.rb', line 237

def validate_options_with( handler )
    @validate_options_with = handler
end

Instance Method Details

#application ⇒ Object 



396
397
398
 
# File 'lib/cuboid/application.rb', line 396

def application
    Cuboid::Application.application
end

#inspect ⇒ Object 



373
374
375
376
377
378
379
 
# File 'lib/cuboid/application.rb', line 373

def inspect
    stats = statistics

    s = "#<#{self.class} (#{status}) "
    s << "runtime=#{stats[:runtime]} "
    s << '>'
end

#options ⇒ Object 



358
359
360
 
# File 'lib/cuboid/application.rb', line 358

def options
    Options.application
end

#options=(opts) ⇒ Object 



354
355
356
 
# File 'lib/cuboid/application.rb', line 354

def options=( opts )
    Options.application = opts
end

#runtime ⇒ Object 



350
351
352
 
# File 'lib/cuboid/application.rb', line 350

def runtime
    @runtime
end

#safe(&block) ⇒ Object

Raises:

  • (ArgumentError) 


404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/cuboid/application.rb', line 404

def safe( &block )
    raise ArgumentError, 'Missing block.' if !block_given?

    begin
        block.call self
    ensure
        clean_up
        reset
    end

    nil
end

#serializer ⇒ Object 



400
401
402
 
# File 'lib/cuboid/application.rb', line 400

def serializer
    self.class.serializer
end

#statistics ⇒ Hash

Returns Framework statistics:

  • ‘:runtime` – Application runtime in seconds.

Returns:

  • (Hash) —

    Framework statistics:

    • ‘:runtime` – Application runtime in seconds.



367
368
369
370
371
 
# File 'lib/cuboid/application.rb', line 367

def statistics
    {
        runtime: @start_datetime ? (@finish_datetime || Time.now) - @start_datetime : 0,
    }
end

#unsafe ⇒ Object 



392
393
394
 
# File 'lib/cuboid/application.rb', line 392

def unsafe
    self
end

#version ⇒ String

Returns the version of the framework.

Returns:

  • (String) —

    Returns the version of the framework.



383
384
385
 
# File 'lib/cuboid/application.rb', line 383

def version
    Cuboid::VERSION
end