Module: Cuboid::Server::InstanceHelpers

Included in:
MCP::Server::Dispatcher, Rest::Server::InstanceHelpers
Defined in:
lib/cuboid/server/instance_helpers.rb

Overview

Shared registry + lookup helpers for the running engine instances any front-end (REST, MCP, scheduler-sync) drives. The two class-variables (‘@@instances`, `@@agents`) are intentionally module-level so every includer sees the same map without explicit cross-process plumbing.

‘spawn` here picks an Agent if one is configured (so grid mode keeps working) or falls back to local `Processes::Instances.spawn`. Sinatra-only surface — `instance_for`, REST-side scheduler-session cleanup, and the env-derived owner URL on `spawn` — lives on `Cuboid::Rest::Server::InstanceHelpers`, which mixes this in.

Constant Summary collapse

@@instances = 
{}
@@agents = 
{}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.agent ⇒ Object 



52
53
54
55
56
 
# File 'lib/cuboid/server/instance_helpers.rb', line 52

def self.agent
    return if !::Cuboid::Options.agent.url
    @@agents[::Cuboid::Options.agent.url] ||=
        ::Cuboid::RPC::Client::Agent.new( ::Cuboid::Options.agent.url )
end

.connect_to_agent(url) ⇒ Object 



58
59
60
 
# File 'lib/cuboid/server/instance_helpers.rb', line 58

def self.connect_to_agent( url )
    @@agents[url] ||= ::Cuboid::RPC::Client::Agent.new( url )
end

.connect_to_instance(url, token) ⇒ Object 



62
63
64
 
# File 'lib/cuboid/server/instance_helpers.rb', line 62

def self.connect_to_instance( url, token )
    ::Cuboid::RPC::Client::Instance.new( url, token )
end

.instances ⇒ Object 



20
21
22
 
# File 'lib/cuboid/server/instance_helpers.rb', line 20

def self.instances
    @@instances
end

.spawn(owner_url: nil) ⇒ Object

Spawn a new engine instance. If an Agent URL is configured the instance is provisioned via the Agent (grid path); otherwise we fork a local one via ‘Processes::Instances.spawn`.

‘owner_url` is forwarded to the Agent as `helpers.owner.url` —purely metadata identifying who asked. Sinatra/REST callers pass `env`; MCP and other non-Rack callers can leave it nil or pass whatever they have. Module-level so callers without an includer context (e.g. `MCP::CoreTools::SpawnInstance`) can use it as `Cuboid::Server::InstanceHelpers.spawn`.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/cuboid/server/instance_helpers.rb', line 34

def self.spawn( owner_url: nil )
    if (a = agent)
        options = {
          owner:   name,
          helpers: { owner: { url: owner_url } }
        }

        if (info = a.spawn( options ))
            connect_to_instance( info['url'], info['token'] )
        end
    else
        ::Cuboid::Processes::Instances.spawn(
            application: ::Cuboid::Options.paths.application,
            daemonize:   true
        )
    end
end

Instance Method Details

#agent ⇒ Object 



70
71
72
 
# File 'lib/cuboid/server/instance_helpers.rb', line 70

def agent
    InstanceHelpers.agent
end

#agents ⇒ Object 



66
67
68
 
# File 'lib/cuboid/server/instance_helpers.rb', line 66

def agents
    @@agents.keys
end

#connect_to_agent(url) ⇒ Object 



85
86
87
 
# File 'lib/cuboid/server/instance_helpers.rb', line 85

def connect_to_agent( url )
    InstanceHelpers.connect_to_agent( url )
end

#connect_to_instance(url, token) ⇒ Object 



89
90
91
 
# File 'lib/cuboid/server/instance_helpers.rb', line 89

def connect_to_instance( url, token )
    InstanceHelpers.connect_to_instance( url, token )
end

#connect_to_scheduler(url) ⇒ Object 



116
117
118
 
# File 'lib/cuboid/server/instance_helpers.rb', line 116

def connect_to_scheduler( url )
    RPC::Client::Scheduler.new( url )
end

#exists?(id) ⇒ Boolean

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/cuboid/server/instance_helpers.rb', line 124

def exists?( id )
    instances.include? id
end

#instances ⇒ Object 



120
121
122
 
# File 'lib/cuboid/server/instance_helpers.rb', line 120

def instances
    InstanceHelpers.instances
end

#scheduler ⇒ Object 



111
112
113
114
 
# File 'lib/cuboid/server/instance_helpers.rb', line 111

def scheduler
    return if !Options.scheduler.url
    @scheduler ||= connect_to_scheduler( Options.scheduler.url )
end

#spawn(owner_url: nil) ⇒ Object 



74
75
76
 
# File 'lib/cuboid/server/instance_helpers.rb', line 74

def spawn( owner_url: nil )
    InstanceHelpers.spawn( owner_url: owner_url )
end

#unplug_agent(url) ⇒ Object 



78
79
80
81
82
83
 
# File 'lib/cuboid/server/instance_helpers.rb', line 78

def unplug_agent( url )
    InstanceHelpers.connect_to_agent( url ).node.unplug

    c = @@agents.delete( url )
    c.close if c
end

#update_from_scheduler ⇒ Object

Pulls scheduler-tracked running instances into the local map and closes/removes any that the scheduler reports failed or completed. Sinatra-side session cleanup for the same IDs is the responsibility of ‘Cuboid::Rest::Server::InstanceHelpers#update_from_scheduler`, which calls super then prunes its session.



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/cuboid/server/instance_helpers.rb', line 98

def update_from_scheduler
    return if !scheduler

    scheduler.running.each do |id, info|
        instances[id] ||= connect_to_instance( info['url'], info['token'] )
    end

    (scheduler.failed.keys | scheduler.completed.keys).each do |id|
        client = instances.delete( id )
        client.close if client
    end
end