Class: Cybertrain::Application

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/feeds.rb,
cybertrain/jobs.rb,
cybertrain/application.rb

Overview

The booted application: config, database, views and the middleware stack in front of the generated router. bin/.rb builds one and hands it Cybertrain::Main's argv:

module Gen::Routes def self.url_resolver = ->(name, args, options) { path_for(name, args, options) } end

app = Cybertrain::Application.new( router: Gen::Routes.build(Cybertrain::Router.new), url_resolver: Gen::Routes.url_resolver, views: Gen::Views::SOURCES, name: “" ) app.run(argv)

views is the table spin run gen -- --embed-views writes to gen/views.rb; production refuses to boot when it is empty (.embedded_views_missing?). name is the spin build target and the binary (build/bin/) the development loop rebuilds and execs.

Do NOT write the resolver as a lambda literal in the keyword position (url_resolver: ->(name, args, options) { ... }), nor pass a local holding one: Spinel 2026.09.12 does not mark a lambda passed as a keyword argument as escaping, so its parameters keep the Integer default and every path helper receives a garbage route name (e.g. 4295868465 instead of “notes_path”) while CRuby works. A method-returned lambda (as above), a positional argument, a block argument or a double-splatted Hash all compile correctly.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.request_stop_roles ⇒ nil

The same as #request_stop_roles, for code (a test, a trap) that does not hold the Application instance Main.run made.

Returns:

  • (nil)


339
340
341
# File 'cybertrain/application.rb', line 339

def self.request_stop_roles
  Roles.request_stop
end

Instance Method Details

#boot ⇒ Application

Boots in three stages (docs/design.md D66): validate (reads only; a problem is error: ... and exit 1), acquire (the secret, the database pool), apply (the views, the process-shared settings). An exception in the second or third stage propagates after #abandon_boot has released what this call acquired, so a retry starts from a defined state.

Returns:



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
# File 'cybertrain/application.rb', line 130

def boot
  validate_boot
  before = @database_generation
  completed = false
  begin
    acquire_boot_resources
    apply_boot_settings
    completed = true
  ensure
    # A flag and an ensure, not a rescue: a rescue clause does not see
    # every exception class under Spinel (NOTES rules 33, 61).
    abandon_boot(before) unless completed
  end
  @booted = true
  self
end

#booted? ⇒ Boolean

Whether #boot has completed (and #shutdown has not run since).

Returns:

  • (Boolean)


251
252
253
# File 'cybertrain/application.rb', line 251

def booted?
  @booted
end

#request_stop_roles ⇒ nil

Ends a run_worker or run_feeds: sets a flag the waiting main thread sees within 0.1 s (and nothing else, so the TERM trap can call it: see serve_development). Also callable from another thread, as tests do.

Returns:

  • (nil)


331
332
333
# File 'cybertrain/application.rb', line 331

def request_stop_roles
  Application.request_stop_roles
end

#run_feeds(names) ⇒ Integer

./<app> feeds [NAME...] (Main.run): boots and runs Roles::FeedsRunner: checks the names against the registered feeds (an unknown one is an error that lists them), starts the WebSocket subscriptions (all of them, or the named ones) and runs until SIGTERM or SIGINT, then stops them. No port, no jobs, no scheduler. With no subscription registered it says so and returns 0.

Parameters:

  • names (Array<String>) —

    the feeds to run; empty for all

Returns:

  • (Integer) —

    the exit status: 0, or 1 for a refused start or after a feed died too often



38
39
40
41
42
43
44
45
46
47
48
# File 'cybertrain/feeds.rb', line 38

def run_feeds(names)
  return run_feeds_status if !names.empty? && names[0] == "status"

  busy = Runtime.role_problem
  return Roles.refuse(busy) unless busy.empty?

  Roles.reset_stop
  @config.worker = true
  boot
  Roles::FeedsRunner.new(@config).run_feeds(names)
end

#run_feeds_status ⇒ Integer

./<app> feeds status: boots (the database), prints one line per feed status row (WebSocket::FeedTable) and returns 0; it starts no feed. The line:

NAME connected disconnected process last activity Ns ago restarts N updated Ns ago

“last activity never” until the feed’s first message. Times are relative to now, so a stale row stands out. A row whose name no registered subscription has (a feed renamed or removed since; /up does not count it) ends with “ (not registered)”. With no rows it says so.

Returns:



63
64
65
66
67
# File 'cybertrain/feeds.rb', line 63

def run_feeds_status
  @config.worker = true
  boot
  Roles::FeedsRunner.new(@config).feeds_status
end

#run_worker(argv) ⇒ Integer

./<app> worker (Main.run): boots (the config checks, the database) and runs Roles::WorkerRunner: a banner, the scheduler (lease-gated: several workers may share the database) and the job threads, until SIGTERM or SIGINT (or Application.request_stop_roles), then their shutdown (the job threads finish their jobs, for at most Config#job_drain_timeout seconds). No port, no HTTP. Config#worker is set: in this role it is what the process is for. Defined here, on the core’s Application, by cybertrain/jobs.

Parameters:

  • argv (Array<String>) —

    what follows worker; must be empty

Returns:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# File 'cybertrain/jobs.rb', line 39

def run_worker(argv)
  unless argv.empty?
    puts "error: worker takes no arguments (got #{argv.join(" ")})"
    STDOUT.flush
    return 1
  end
  # Before anything shared changes: a second role in a process that
  # runs one must not clear its stop flag or re-apply the settings.
  busy = Runtime.role_problem
  return Roles.refuse(busy) unless busy.empty?

  # Before boot: a stop asked for while booting is kept.
  Roles.reset_stop
  @config.worker = true
  boot
  Roles::WorkerRunner.new(@config).run_worker
end

#shutdown ⇒ nil

Ends what #boot began: closes the database pool if this Application’s boot connected it (a pool the caller connected, or one connected since, is left open) and marks the Application not booted. The process-shared settings stay as the boot left them until the next boot or Runtime.reset!. Call it after #serve, #run_worker or #run_feeds has returned (they stop their own threads), never while one runs. Scheduler.stop! asks the scheduler to stop without waiting for a task in progress, so an in-process caller that shuts down right after a role returned should let a running Scheduler task finish first: it would find the pool closed (DB::Error). #boot may be called again afterwards.

Returns:

  • (nil)


268
269
270
271
272
273
274
275
276
# File 'cybertrain/application.rb', line 268

def shutdown
  DB.disconnect if @database_generation >= 0 && DB.connected? && DB.generation == @database_generation
  @database_generation = -1
  @booted = false
  # A later boot may serve on another port or with a changed config: the
  # runner (and the HTTP server it built) is this lifecycle's.
  @server_runner = nil
  nil
end