railwatch-sidecar 0.2.0-x86_64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,150 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Railwatch
4
+ module Sidecar
5
+ # Everything is an env var first (RAILWATCH_SIDECAR_*), then assignment in
6
+ # an initializer:
7
+ #
8
+ # Railwatch::Sidecar.configure do |c|
9
+ # c.port = 28790
10
+ # c.user = ->(controller) { { email: controller.current_user.email, name: controller.current_user.name, role: "admin" } }
11
+ # end
12
+ #
13
+ # The dashboard's gate is the railwatch gem's (Railwatch.config): HTTP
14
+ # Basic on and closed by default, or `base_controller_class` with Basic
15
+ # off. One set of credentials for /railwatch whichever gem serves it.
16
+ class Configuration
17
+ attr_accessor :enabled, :port, :data_dir, :mount_path, :binary, :url, :stop_timeout, :setup_timeout, :user, :wire_agent,
18
+ :max_live_connections, :max_proxied_requests, :proxy_connect_timeout, :proxy_first_byte_timeout,
19
+ :proxy_idle_timeout, :nice, :smtp, :mail_from, :backup, :google, :retention, :alert_delivery, :server_env,
20
+ :agent_access
21
+
22
+ def initialize
23
+ # nil: on, except under Rails.env.test (a test run on a machine with
24
+ # a development server running would report into it). See #enabled.
25
+ @enabled = env_bool("RAILWATCH_SIDECAR_ENABLED", nil)
26
+ # One fixed port per app, not a free one picked at boot: every process
27
+ # of the app (Puma workers, Solid Queue, a rake task) must find the
28
+ # server without asking, and a second Puma on the same host and data
29
+ # dir must hit the same server (docs: two processes, one data dir).
30
+ @port = Integer(setting("RAILWATCH_SIDECAR_PORT", "28790"))
31
+ # nil: storage/railwatch/<Rails.env>, one per environment, as Rails
32
+ # keeps storage/<env>.sqlite3. See #data_path.
33
+ @data_dir = setting("RAILWATCH_SIDECAR_DATA_DIR")
34
+ @mount_path = setting("RAILWATCH_SIDECAR_MOUNT_PATH", "/railwatch")
35
+ # A railwatch binary of your own (another version, a platform this
36
+ # gem has no build for). Default: the one in this platform's gem.
37
+ @binary = setting("RAILWATCH_SIDECAR_BINARY")
38
+ # The public URL of the dashboard's host, for links in alert emails
39
+ # and the Secure cookie flag. Default: the loopback address.
40
+ @url = setting("RAILWATCH_SIDECAR_URL")
41
+ # How long Puma's exit waits for the server to drain after TERM. The
42
+ # server answers SIGTERM by finishing in-flight requests and committing
43
+ # queued writes; an idle one is gone in well under a second.
44
+ @stop_timeout = Float(setting("RAILWATCH_SIDECAR_STOP_TIMEOUT", "15"))
45
+ # How long the first start of a data dir waits for `railwatch setup`
46
+ # (it takes about a second), before Puma listens. Past it the setup is
47
+ # KILLed and the app boots without the server; the next start retries.
48
+ @setup_timeout = Float(setting("RAILWATCH_SIDECAR_SETUP_TIMEOUT", "30"))
49
+ # Who the dashboard's visitor is, as the server should see them:
50
+ # ->(controller) { { email:, name:, role: "admin" | "member" } }.
51
+ @user = nil
52
+ # Whether <mount>/mcp and <mount>/api/ (what an AI agent calls) are
53
+ # signed for the visitor like the dashboard, so the agent needs no
54
+ # token. nil: only in development, for a request from this machine
55
+ # to a local host name (ProxyController#agent_access?). true: for
56
+ # every request that passes the gate, in any environment. false:
57
+ # never; an agent sends a token (Authorization: Bearer rwp_...).
58
+ @agent_access = env_bool("RAILWATCH_SIDECAR_AGENT_ACCESS", nil)
59
+ # Point the railwatch agent at the bundled server when the app has not
60
+ # configured one (no RAILWATCH_TOKEN). Off: the app wires it itself.
61
+ @wire_agent = env_bool("RAILWATCH_SIDECAR_WIRE_AGENT", true)
62
+ # Open live-channel connections (one per dashboard tab) per app
63
+ # process, all spliced by one relay thread. Past it the dashboard
64
+ # still works, without live updates.
65
+ @max_live_connections = Integer(setting("RAILWATCH_SIDECAR_MAX_LIVE_CONNECTIONS", "64"))
66
+ # Dashboard requests waiting on the server or streaming back, per app
67
+ # process, all moved by that same relay thread instead of a Puma
68
+ # thread each. Past it a dashboard request gets 503 and Retry-After
69
+ # at once; the app's own requests are never affected.
70
+ @max_proxied_requests = Integer(setting("RAILWATCH_SIDECAR_MAX_PROXIED_REQUESTS", "64"))
71
+ # Seconds: to connect to the server (on loopback: it is down, or past
72
+ # its own connection cap), for it to start answering a dashboard
73
+ # request (504 past it; the slowest page at 30 days takes seconds),
74
+ # and for a response that has started to move again (cut off past it).
75
+ # The first-byte timeout is under the 30 s after which Thruster and
76
+ # kamal-proxy drop a response that has not started: past theirs the
77
+ # visitor gets an empty reply, under it this proxy's 504 that says why.
78
+ @proxy_connect_timeout = Float(setting("RAILWATCH_SIDECAR_PROXY_CONNECT_TIMEOUT", "2"))
79
+ @proxy_first_byte_timeout = Float(setting("RAILWATCH_SIDECAR_PROXY_FIRST_BYTE_TIMEOUT", "25"))
80
+ @proxy_idle_timeout = Float(setting("RAILWATCH_SIDECAR_PROXY_IDLE_TIMEOUT", "60"))
81
+ # How much lower than the app's the server's CPU priority is (nice
82
+ # increment, 0-19; 0 keeps the app's). The server can keep every core
83
+ # busy rendering dashboards; at 10 the app's requests come first. Not
84
+ # under a CPU quota (docker --cpus, Kubernetes limits), which stalls
85
+ # the app with the server whatever the priority.
86
+ @nice = Integer(setting("RAILWATCH_SIDECAR_NICE", "10"))
87
+ # The server's own settings (Settings): nil means "from the app"
88
+ # (Action Mailer's SMTP and From, credentials.railwatch_sidecar's
89
+ # backup and google), false/{} turns one off.
90
+ # smtp: { address:, port:, user_name:, password:, enable_starttls:, tls: }
91
+ # backup: { endpoint:, bucket:, access_key_id:, secret_access_key:, region:, prefix:, interval_seconds: }
92
+ # google: { client_id:, client_secret: }
93
+ # retention: { detail_days:, core_days_max: }
94
+ @smtp = nil
95
+ @mail_from = nil
96
+ @backup = nil
97
+ @google = nil
98
+ @retention = nil
99
+ # true/false: send alerts or only record them. nil: the server's default (on).
100
+ @alert_delivery = nil
101
+ # Any other RAILWATCH_* setting of the server, by name.
102
+ @server_env = {}
103
+ end
104
+
105
+ def enabled
106
+ @enabled.nil? ? environment != "test" : @enabled
107
+ end
108
+
109
+ # The environment the server's data dir holds: Rails.env, else
110
+ # RAILS_ENV/RACK_ENV, else production. One per data dir.
111
+ def environment
112
+ (defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env : ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "production").to_s
113
+ end
114
+
115
+ def data_path
116
+ path = Pathname.new(data_dir || File.join("storage", "railwatch", environment))
117
+ path.relative? && defined?(Rails) && Rails.root ? Rails.root.join(path) : path.expand_path
118
+ end
119
+
120
+ def local_url = "http://127.0.0.1:#{port}"
121
+
122
+ def normalized_mount_path
123
+ "/#{mount_path.to_s.delete_prefix('/').delete_suffix('/')}"
124
+ end
125
+
126
+ private
127
+
128
+ # RAILWATCH_SIDECAR_<NAME>, else the pre-rename RAILWATCH_SERVER_<NAME>
129
+ # (railwatch-server, before 0.2), which still works and warns once.
130
+ def setting(name, default = nil)
131
+ value = ENV[name]
132
+ return value unless value.nil?
133
+
134
+ old = name.sub("RAILWATCH_SIDECAR_", "RAILWATCH_SERVER_")
135
+ value = ENV[old]
136
+ return default if value.nil?
137
+
138
+ Railwatch::Sidecar.deprecated("#{old} is now #{name}")
139
+ value
140
+ end
141
+
142
+ def env_bool(name, default)
143
+ value = setting(name)
144
+ return default if value.nil? || value.strip.empty?
145
+
146
+ %w[1 true yes on].include?(value.strip.downcase)
147
+ end
148
+ end
149
+ end
150
+ end
@@ -0,0 +1,155 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "open3"
5
+ require "securerandom"
6
+
7
+ module Railwatch
8
+ module Sidecar
9
+ # The server's data directory under the app (storage/railwatch by
10
+ # default) and what this gem keeps in it next to the server's own files:
11
+ #
12
+ # control.sqlite3, telemetry/, serve.lock, secret_key_base the server's
13
+ # proxy_secret the HMAC key the /railwatch proxy signs with (0600)
14
+ # ingest_token the first environment's rw_ token (0600), so every
15
+ # process of the app can report without asking
16
+ # server.log the server's stdout and stderr
17
+ # server.env the server's settings from the app (Settings, 0600)
18
+ # environment the Rails environment it holds (one per data dir)
19
+ #
20
+ # Provisioning runs `railwatch setup` once, before the first `serve`:
21
+ # setup refuses a data dir that already has users, so it is idempotent by
22
+ # construction, and the token it prints is written down here because the
23
+ # server keeps only its digest.
24
+ #
25
+ # It runs before Puma listens, so it has a deadline (setup_timeout): past
26
+ # it the setup's process group is KILLed and provisioning fails, and the
27
+ # app boots without the server. A setup that fails, by deadline or exit
28
+ # status, leaves no ingest_token (so the dir is not provisioned?), and
29
+ # what it had created is removed: users it had committed would make every
30
+ # later setup refuse the dir ("already has users").
31
+ class DataDir
32
+ SETUP_LOCK = "provision.lock"
33
+
34
+ attr_reader :path
35
+
36
+ def initialize(path)
37
+ @path = Pathname.new(path)
38
+ end
39
+
40
+ def proxy_secret_file = path.join("proxy_secret")
41
+ def token_file = path.join("ingest_token")
42
+ def log_file = path.join("server.log")
43
+ def settings_file = path.join("server.env")
44
+ def environment_file = path.join("environment")
45
+
46
+ # The Rails environment this data dir was provisioned for. Data dirs
47
+ # provisioned before the file existed say nothing.
48
+ def environment
49
+ environment_file.read.strip if environment_file.exist?
50
+ end
51
+
52
+ def token
53
+ token_file.read.strip if token_file.exist?
54
+ end
55
+
56
+ def proxy_secret
57
+ proxy_secret_file.read.strip if proxy_secret_file.exist?
58
+ end
59
+
60
+ def provisioned?
61
+ token_file.exist? && proxy_secret_file.exist?
62
+ end
63
+
64
+ # Creates the directory, the proxy secret and (through `railwatch
65
+ # setup`) the admin, account, app and environment, once. Two processes
66
+ # booting together take turns on an flock, so only one runs setup; the
67
+ # wait for it counts against the same timeout, so workers that each
68
+ # provision (a bare `puma` in cluster mode) are not held up one after
69
+ # another. Returns what it did, for the log.
70
+ def provision!(binary:, env:, app_name:, env_name:, timeout:)
71
+ FileUtils.mkdir_p(path, mode: 0o700)
72
+ deadline = monotonic + timeout
73
+ done = []
74
+ File.open(path.join(SETUP_LOCK), File::RDWR | File::CREAT, 0o600) do |lock|
75
+ until lock.flock(File::LOCK_EX | File::LOCK_NB)
76
+ if monotonic >= deadline
77
+ raise Error, "another process has been provisioning #{path} for #{timeout}s (RAILWATCH_SIDECAR_SETUP_TIMEOUT); " \
78
+ "this one boots without the Railwatch server and tries again at its next start"
79
+ end
80
+ sleep 0.05
81
+ end
82
+ unless proxy_secret_file.exist?
83
+ write_secret(proxy_secret_file, SecureRandom.hex(32))
84
+ done << "proxy secret"
85
+ end
86
+ unless token_file.exist?
87
+ write_secret(token_file, setup!(binary, env, app_name, env_name, timeout, [ deadline - monotonic, 0.1 ].max))
88
+ done << "admin, account, #{app_name}/#{env_name} and its ingest token"
89
+ end
90
+ File.write(environment_file, "#{env_name}\n") unless environment_file.exist?
91
+ end
92
+ done
93
+ end
94
+
95
+ private
96
+
97
+ def write_secret(file, value)
98
+ tmp = file.sub_ext(".tmp")
99
+ File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write("#{value}\n") }
100
+ File.rename(tmp, file)
101
+ end
102
+
103
+ # The admin's password is random and thrown away: nobody signs in with
104
+ # it. People reach the dashboard through the app's own gate, and the
105
+ # proxy names them (ProxyAuth); the admin is only the account's owner.
106
+ def setup!(binary, env, app_name, env_name, timeout, left)
107
+ password = SecureRandom.base58(32)
108
+ before = path.children
109
+ out, err, status = run_setup(left, env, binary, "setup", "--email", "railwatch-owner@localhost.invalid", "--name", "Railwatch",
110
+ "--account", app_name, "--app", app_name, "--env", env_name, "--password-stdin",
111
+ stdin_data: "#{password}\n")
112
+ token = out[/RAILWATCH_TOKEN=(rw_\S+)/, 1]
113
+ return token if status&.success? && token
114
+
115
+ (path.children - before).each { FileUtils.rm_rf(_1) }
116
+ unless status
117
+ raise Error, "railwatch setup did not finish within #{timeout}s (RAILWATCH_SIDECAR_SETUP_TIMEOUT); KILLED it. " \
118
+ "The app boots without the Railwatch server: the agent is not wired and the dashboard is unavailable. " \
119
+ "The next start runs setup again#{"; it printed: #{err.strip.lines.last(5).join.strip}" if err.strip != ""}"
120
+ end
121
+ if err.include?("already has users")
122
+ raise Error, "#{path} already has a Railwatch server with users but no #{token_file.basename}: " \
123
+ "create a token with `#{binary} env create <slug>` (RAILWATCH_DATA_DIR=#{path}) and write it to #{token_file}"
124
+ end
125
+ raise Error, "railwatch setup failed (exit #{status.exitstatus}): #{err.strip.presence || out.strip}"
126
+ end
127
+
128
+ # Open3.capture3 with a deadline: [stdout, stderr, status], status nil
129
+ # when the deadline passed and the setup's process group was KILLed.
130
+ def run_setup(timeout, *command, stdin_data:)
131
+ Open3.popen3(*command, pgroup: true) do |stdin, stdout, stderr, wait|
132
+ out = Thread.new { stdout.read }
133
+ err = Thread.new { stderr.read }
134
+ begin
135
+ stdin.write(stdin_data)
136
+ rescue Errno::EPIPE
137
+ nil
138
+ end
139
+ stdin.close
140
+ return [ out.value, err.value, wait.value ] if wait.join(timeout)
141
+
142
+ begin
143
+ ::Process.kill(:KILL, -wait.pid)
144
+ rescue Errno::ESRCH
145
+ nil
146
+ end
147
+ wait.join
148
+ [ out.join(1)&.value.to_s, err.join(1)&.value.to_s, nil ]
149
+ end
150
+ end
151
+
152
+ def monotonic = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
153
+ end
154
+ end
155
+ end
@@ -0,0 +1,58 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Railwatch
4
+ module Sidecar
5
+ # An engine only for its app/controllers (autoloaded, so the proxy can
6
+ # inherit from the app's own base controller) and lib/tasks (an engine
7
+ # loads those itself); the route is the app's, prepended so no catch-all
8
+ # of the app shadows it.
9
+ class Engine < ::Rails::Engine
10
+ initializer "railwatch_sidecar.routes" do |app|
11
+ next unless Railwatch::Sidecar.enabled?
12
+
13
+ mount = Railwatch::Sidecar.config.normalized_mount_path
14
+ app.routes.prepend do
15
+ match "#{mount}(/*path)", to: "railwatch/sidecar/proxy#forward", via: :all, format: false,
16
+ as: :railwatch_sidecar_dashboard
17
+ end
18
+ end
19
+
20
+ # Outside every other middleware (the railwatch agent's included), so
21
+ # the app's session and cookies are written before the browser's socket
22
+ # is handed to the relay (ProxyHandoff).
23
+ initializer "railwatch_sidecar.handoff" do |app|
24
+ next unless Railwatch::Sidecar.enabled?
25
+
26
+ app.middleware.insert_before 0, Railwatch::Sidecar::ProxyHandoff
27
+ end
28
+
29
+ # After the app's initializers (and the railwatch gem's credentials
30
+ # lookup), before the railwatch gem's reporter adopts its final config.
31
+ initializer "railwatch_sidecar.agent", after: :load_config_initializers, before: "railwatch.adopt_final_config" do
32
+ next unless Railwatch::Sidecar.enabled?
33
+
34
+ # The dashboard's own requests (every page, each live refresh) are
35
+ # not the app's traffic: recording them would also make each view a
36
+ # new ingest, which pings the live channel, which refetches the page.
37
+ mount = Railwatch::Sidecar.config.normalized_mount_path
38
+ Railwatch.config.ignored_request_paths |= [ %r{\A#{Regexp.escape(mount)}(/|\z)} ]
39
+
40
+ case Railwatch::Sidecar.wire_agent!
41
+ when :wired
42
+ Rails.logger.info("[railwatch-sidecar] the railwatch agent reports to #{Railwatch::Sidecar.config.local_url}")
43
+ when :not_provisioned
44
+ Rails.logger.warn("[railwatch-sidecar] #{Railwatch::Sidecar.data_dir.path} is not provisioned yet, so this process's agent is not wired: " \
45
+ "the server's process creates it the first time it starts (Puma with `plugin :railwatch_sidecar`, or " \
46
+ "railwatch_sidecar:start); this process reports once it restarts after that")
47
+ when :configured_elsewhere
48
+ Rails.logger.info("[railwatch-sidecar] the railwatch agent is configured elsewhere (RAILWATCH_TOKEN); " \
49
+ "the bundled server only serves the dashboard")
50
+ end
51
+ rescue Railwatch::Sidecar::Error, Railwatch::Sidecar::Binary::NotFound => e
52
+ # Loud and not fatal: the app boots, the dashboard says what is wrong.
53
+ Rails.logger.error("[railwatch-sidecar] #{e.message}")
54
+ warn("[railwatch-sidecar] #{e.message}")
55
+ end
56
+ end
57
+ end
58
+ end