railwatch-server 0.1.9 → 0.2.0

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4bb715424ae50b992f68953cd6956fc38728fbe1a865b9dfd18564e6651c8a94
4
- data.tar.gz: 64cbe87ab706c64753fbdfd87dac69dd39703972903ee8757297c396910183a8
3
+ metadata.gz: 387f28b80bdf2d02aec39648dacc446a0756a89cbacaca7b1fa926d0f18871ed
4
+ data.tar.gz: 20f9d764595440b26ff493e03442379402355eaab6932d730e14fd9c11863647
5
5
  SHA512:
6
- metadata.gz: 8c76e53755ffaa27b3a63254e86c30e31579639d9ef62218c6f342a636d0fe0655de5143816ed6caadf9af175f14275c61503da57b614df19b5984603a9fa360
7
- data.tar.gz: ca10413e63096afde8b028912d3fe2e1dbcdfe5ec2fd8fda858bf975b9f902b65ec8089a6525aaddf5cc974a7c168be61f47b2c2b8cf2185a9d8e4a644862708
6
+ metadata.gz: 50c5022aee5680e25dcf3115e8c8450a622ff1730dbd61428b8270a27df4470a3c6b52aac0fa7459ff4ccfd1375c58ae2c3e4710f6ea0f3e04924721737be8bc
7
+ data.tar.gz: ab3681ebd16b35749c6f7c2dd33ac58e3bb074a69d052191f54a16c0251b0182c18559fcb573ef288097f7cc9fc52b021d0b2b398167afe85dc0c7789bc1b3ac
data/README.md CHANGED
@@ -1,429 +1,12 @@
1
- # railwatch-server
1
+ # railwatch-server → railwatch-sidecar
2
2
 
3
- The Railwatch server, bundled as a gem. Add it to a Rails app and you get
4
- the **full** Railwatch dashboard at `/railwatch` (issues, alerts, the API
5
- and MCP included), behind your app's own login, with no server to install.
6
- The server runs as **its own process** next to the app, started by Puma's
7
- master. It never runs inside a Puma worker.
8
-
9
- ## How it relates to the other two
10
-
11
- | | what it is | license |
12
- |---|---|---|
13
- | [`railwatch`](https://github.com/Rebulk/railwatch) | the agent in your app; on its own it reports to Railwatch Cloud or a self-hosted server | MIT |
14
- | [`railwatch-rs`](https://github.com/Rebulk/railwatch-rs) | the server, one static binary; self-hosted on a VPS for many apps | FSL-1.1-ALv2 |
15
- | **`railwatch-server`** (this) | `railwatch-rs`, prebuilt per platform, run and wired for one app | FSL-1.1-ALv2 |
16
-
17
- This gem depends on `railwatch` and points the agent at the bundled server.
18
- It is the same server you would self-host, at the same version, just started
19
- for you. Moving later to a shared self-hosted install means changing
20
- `RAILWATCH_INGEST_URL` and `RAILWATCH_TOKEN` (and copying `storage/railwatch`
21
- if you want the history).
22
-
23
- ## Install
3
+ This gem was renamed **[railwatch-sidecar](https://github.com/Rebulk/railwatch-sidecar)**.
4
+ Version 0.2.0 of `railwatch-server` only depends on it.
24
5
 
25
6
  ```ruby
26
7
  # Gemfile
27
- gem "railwatch"
28
- gem "railwatch-server"
29
- ```
30
-
31
- ```ruby
32
- # config/puma.rb
33
- plugin :railwatch_server
34
- ```
35
-
36
- ```ruby
37
- # config/initializers/railwatch.rb: the dashboard's gate (the railwatch gem's settings)
38
- Railwatch.configure do |c|
39
- c.http_basic_auth_user = "admin" # or bin/rails railwatch:authentication:configure
40
- c.http_basic_auth_password = ENV["RAILWATCH_DASHBOARD_PASSWORD"]
41
- end
42
- ```
43
-
44
- `bin/rails s`, then open `/railwatch`. On first boot the gem runs
45
- `railwatch setup` against `storage/railwatch/<Rails.env>`, so the account,
46
- app, environment, ingest token and proxy secret are created once and kept
47
- there. It then starts `railwatch serve` on `127.0.0.1:28790` and points the
48
- agent at it.
49
-
50
- Only a process that starts the server creates that directory: Puma with the
51
- plugin (`bin/rails server` or `puma`) and `bin/rails railwatch_server:start`.
52
- Anything else (`assets:precompile` in a Dockerfile, a console, a Solid Queue
53
- worker) reads it and, until it exists, leaves the agent alone and says so.
54
- So an image build ships no token, proxy secret or `secret_key_base`; each
55
- volume gets its own on first start. A job worker started before the first
56
- server reports from its next restart. A `railwatch setup` that hangs never
57
- holds up the boot past `RAILWATCH_SERVER_SETUP_TIMEOUT` (below).
58
-
59
- Bundler picks the platform gem with the binary for your machine:
60
- x86_64-linux, aarch64-linux, x86_64-darwin or arm64-darwin. On anything
61
- else the plain gem installs and tells you to set `RAILWATCH_SERVER_BINARY`
62
- to a `railwatch` you installed yourself.
63
-
64
- ### Without Puma
65
-
66
- Use `bin/rails railwatch_server:start` (foreground, TERM to stop), e.g. as a
67
- Procfile line:
68
-
69
- ```
70
- railwatch: bin/rails railwatch_server:start
71
- ```
72
-
73
- `bin/rails railwatch_server:status` reports the binary, the data dir,
74
- whether the server is up, and where the agent reports.
75
-
76
- ## Configuration
77
-
78
- | env | default | |
79
- |---|---|---|
80
- | `RAILWATCH_SERVER_ENABLED` | on, off under `Rails.env.test` | off: no server, no route, the agent untouched |
81
- | `RAILWATCH_SERVER_PORT` | `28790` | loopback port. Fixed, not picked at boot, so every process of the app finds the same server |
82
- | `RAILWATCH_SERVER_DATA_DIR` | `storage/railwatch/<Rails.env>` | put it on the volume that survives deploys |
83
- | `RAILWATCH_SERVER_MOUNT_PATH` | `/railwatch` | |
84
- | `RAILWATCH_SERVER_URL` | the loopback URL | public URL of the app, for links in alert emails and Secure cookies |
85
- | `RAILWATCH_SERVER_BINARY` | the platform gem's | your own `railwatch` |
86
- | `RAILWATCH_SERVER_STOP_TIMEOUT` | `15` | seconds Puma's exit waits for the server to drain |
87
- | `RAILWATCH_SERVER_SETUP_TIMEOUT` | `30` | seconds the first start of a data dir waits for `railwatch setup` (about a second), before Puma listens. Past it the setup is KILLed, the app boots without the server (agent not wired, the dashboard's 503 says why) and the next start retries |
88
- | `RAILWATCH_SERVER_WIRE_AGENT` | `true` | off: you configure the agent yourself |
89
- | `RAILWATCH_SERVER_MAX_LIVE_CONNECTIONS` | `64` | open live-update connections per app process (one per dashboard tab); past it the dashboard works without live updates |
90
- | `RAILWATCH_SERVER_MAX_PROXIED_REQUESTS` | `64` | dashboard requests in flight per app process (waiting on the server or streaming back); past it a dashboard request gets 503 with `Retry-After: 1` at once. The app's own requests are never affected |
91
- | `RAILWATCH_SERVER_PROXY_CONNECT_TIMEOUT` | `2` | seconds to connect to the server on loopback; past it, 503 |
92
- | `RAILWATCH_SERVER_PROXY_FIRST_BYTE_TIMEOUT` | `25` | seconds for the server to start answering a dashboard request; past it, 504 with a message. Under 30 s on purpose: Thruster (its write timeout) and kamal-proxy drop a response that hasn't started after 30 s, and the visitor gets an empty reply instead |
93
- | `RAILWATCH_SERVER_PROXY_IDLE_TIMEOUT` | `60` | seconds a response that has started may go without a byte moving; past it the connection is closed |
94
- | `RAILWATCH_SERVER_AGENT_ACCESS` | on in development for this machine only, off elsewhere | whether `<mount>/mcp` and `<mount>/api/` (an AI agent's requests) are signed for the visitor like the dashboard, so the agent needs no token. See [AI agents](#ai-agents) |
95
- | `RAILWATCH_SERVER_NICE` | `10` | how far below the app's CPU priority the server runs (0-19; 0: the same). A busy dashboard can keep every core busy; measured in a 2-CPU container under 30 dashboard clients at the app's priority, the app's `/up` p50 went from 2 to 15 ms. Not under a CPU quota (`docker --cpus`, Kubernetes CPU limits): the kernel throttles the container's processes together whatever their priority, and in that 2-CPU container under `--cpus 2` nice 10 measured no better than nice 0 (`/up` p99 190-580 ms at either); on 2 dedicated cores (`--cpuset-cpus`) it took `/up` p99 from 207-363 ms to 18-22 ms. In a quota-limited container give it real cores (a cpuset, or a VM) or keep dashboard use light |
96
-
97
- **Environments.** One environment per data dir, named after `Rails.env`:
98
- development, staging and production usually run on different machines,
99
- and each keeps its own history in `storage/railwatch/<env>`. Under
100
- `Rails.env.test` the server is off by default (a test run would otherwise
101
- report into the development server). The data dir records the environment
102
- it was set up for (`environment`), and an app booted in another
103
- environment against it refuses to wire the agent and says so, rather than
104
- filing staging's telemetry under production. To see several environments
105
- in one dashboard, run one shared self-hosted `railwatch-rs` and point each
106
- environment's agent at it (`RAILWATCH_INGEST_URL`, `RAILWATCH_TOKEN`).
107
-
108
- **The server's own settings** (alert and digest email, backups, Google
109
- sign-in, retention, whether alerts are sent) come from the app, written on
110
- every server start to `<data dir>/server.env` (0600) and never logged
111
- (the log names only what was set: "settings from the app: smtp, backup"):
112
-
113
- | server setting | from |
114
- |---|---|
115
- | SMTP | `config.smtp`, else Action Mailer's `smtp_settings` when `delivery_method` is `:smtp` |
116
- | From | `config.mail_from`, else `ActionMailer::Base.default[:from]` |
117
- | S3 backups | `config.backup`, else `credentials.railwatch_server.backup` (`endpoint bucket access_key_id secret_access_key`, optional `region prefix interval_seconds`) |
118
- | Google sign-in | `config.google`, else `credentials.railwatch_server.google` (`client_id client_secret`) |
119
- | retention | `config.retention = { detail_days:, core_days_max: }` |
120
- | alert delivery | `config.alert_delivery = false` records alerts without sending |
121
- | anything else | `config.server_env = { "RAILWATCH_NEW_ISSUES_PER_HOUR" => 50 }` |
122
-
123
- `false` or `{}` turns one off where the app would otherwise supply it. An
124
- incomplete backup is refused whole (logged, no backups) rather than
125
- half-applied. `railwatch doctor` with `RAILWATCH_ENV_FILE` pointed at the
126
- file shows what the server reads.
127
-
128
- The agent is wired only when the app has not configured a destination:
129
- when `RAILWATCH_TOKEN` is set, it is left alone and the bundled server
130
- serves only the dashboard.
131
-
132
- **Who the server sees.** The dashboard's gate is the `railwatch` gem's:
133
- HTTP Basic, on and closed by default; or, with Basic off,
134
- `base_controller_class` (the proxy controller inherits from it, so your
135
- `before_action :require_admin` runs first). Past the gate, the visitor is
136
- named to the server by `Railwatch::Server.config.user`:
137
-
138
- ```ruby
139
- Railwatch::Server.configure do |c|
140
- c.user = ->(controller) { u = controller.current_user; { email: u.email, name: u.name, role: u.admin? ? "admin" : "member" } }
141
- end
142
- ```
143
-
144
- Without it, the HTTP Basic user name (or "Operator") is an admin. Users are
145
- created in the server on first sight. Nobody signs in to the server itself.
146
-
147
- ## AI agents
148
-
149
- The server's MCP endpoint and JSON API are under the mount too
150
- (`/railwatch/mcp`, `/railwatch/api/v1`). The bundled railwatch-rs takes the
151
- proxy's signed user on them, so an agent on the same machine needs no token
152
- in development:
153
-
154
- ```sh
155
- claude mcp add --transport http railwatch http://localhost:3000/railwatch/mcp
8
+ gem "railwatch-sidecar" # was: gem "railwatch-server"
156
9
  ```
157
10
 
158
- (or `bin/rails generate railwatch:agents` from the railwatch gem, which
159
- writes `.mcp.json` and the instructions). The proxy signs those requests
160
- for the visitor exactly as it signs dashboard pages, and the server takes
161
- the signed header as that user on MCP and the API: every read tool, and the
162
- issue writes (`update_issue`, `add_comment`), attributed to the user and
163
- "agent".
164
-
165
- **What that opens, and to whom.** By default (`agent_access` unset) only
166
- when all of these hold:
167
-
168
- - `Rails.env.development?` (the server's environment, `config.environment`);
169
- - the request comes from this machine (`request.local?`: `127.0.0.1` or
170
- `::1`). A dev server bound to `0.0.0.0` still refuses the LAN;
171
- - its `Host` is `localhost`, `127.0.0.1` or `::1`. A web page whose own name
172
- was rebound to `127.0.0.1` (DNS rebinding) arrives under that name, not
173
- these, and gets no signature;
174
- - the dashboard's gate passes, as for any page (open in development unless
175
- you configured HTTP Basic or a base controller).
176
-
177
- The server also refuses a signed MCP or API request the browser marks as
178
- coming from another site (`Origin` that is not the `Host`, or
179
- `Sec-Fetch-Site: cross-site`), so a page you visit can't call them through
180
- your browser. What is left: anything that can send a request to
181
- `localhost:3000` from your machine (another local user, a local process)
182
- can read the development app's telemetry and comment on its issues. That is
183
- already true of the dashboard at `/railwatch` in development, and of the
184
- dev app itself.
185
-
186
- Everywhere else agent requests are forwarded without the visitor and the
187
- server answers 401 until the agent sends a token (`Authorization: Bearer
188
- rwp_...` from Settings -> Profile), which the proxy passes through
189
- unchanged; a token always wins over the signature, in development too.
190
- `config.agent_access = true` (or `RAILWATCH_SERVER_AGENT_ACCESS=1`) signs
191
- agent requests for whoever passes the gate in any environment: only behind
192
- a gate that authenticates people (`base_controller_class` with your login),
193
- since the agent then acts as them. `false` turns it off in development too.
194
-
195
- ## How it works
196
-
197
- ```
198
- browser ── /railwatch/* ──> Rails (gate) ──> ProxyController ── 127.0.0.1:28790 ──> railwatch serve
199
- + X-Railwatch-Proxy-Auth (signed, 60 s) (RAILWATCH_BASE_PATH=/railwatch)
200
- Puma workers, jobs ── railwatch agent ── /ingest ─────────────────────────────────────┘
201
- ```
202
-
203
- - **Process.** `plugin :railwatch_server` spawns `railwatch serve` from
204
- Puma's master after boot, in its own process group: a Ctrl-C reaches
205
- Puma, Puma drains, and only then is the server stopped. A supervisor
206
- thread checks every second and restarts a dead server with backoff
207
- (1, 2, 4, 8, 15, 30 s), logging the death and the last lines of
208
- `storage/railwatch/server.log`. Each check also asks the server's `/up`
209
- (2 s timeout): one that is alive but stops answering (stopped, wedged)
210
- is logged once as NOT ANSWERING, and after 8 s more of silence is
211
- KILLed and restarted the same way (measured: a SIGSTOPped server was
212
- replaced and answering in 11 s). At boot Puma waits at most 5 s for a
213
- new server's `/up`, then boots without it and says so; a server that
214
- hasn't answered once within 60 s of starting is killed and restarted. On stop: the railwatch agent's samplers
215
- stop, the reporter flushes into the still-running server, then the
216
- server gets SIGTERM (finishes in-flight requests, commits queued writes)
217
- and KILL past the deadline. `server.pid` records "server parent"; a
218
- server orphaned by a SIGKILLed Puma is stopped by the next start.
219
- - **Proxy.** `/railwatch/*` is a prepended route to
220
- `Railwatch::Server::ProxyController`. It forwards the server's cookies
221
- and Inertia headers, sets `Host`/`X-Forwarded-Proto`, sets
222
- `X-Forwarded-For` to the visitor's `request.remote_ip` (replacing any the
223
- browser sent; the server runs with `RAILWATCH_TRUST_PROXY`, so its per-IP
224
- sign-in and MCP limits count visitors, not the app), adds the signed
225
- header, and hands the request off: **no Puma thread waits for the
226
- server.** Past the gate the controller connects to the server and leaves
227
- the request to `ProxyHandoff`, a middleware outside every other one,
228
- which takes the browser's socket with Rack hijack and gives both
229
- sockets to the process's one `Relay` thread (the live channel's, below).
230
- The Relay writes the request (Puma has already read the body; a large
231
- one comes from Puma's tempfile) and passes the response back as it
232
- arrives, byte for byte except the head: `Connection: close` (the browser,
233
- or the proxy in front of the app, opens a new connection for the next
234
- request) and the app's own `Set-Cookie` (a rolling session) added. A
235
- response the server hasn't started within the first-byte timeout is a
236
- 504 and one it drops before answering a 502, both written by the Relay;
237
- one that goes quiet mid-body is cut off after the idle timeout.
238
- Measured (`test/e2e/slow_dashboard.rb`, Puma 1 worker x 3 threads, pages
239
- taking 3 s): before, 6 slow loads made the app's `/up` wait 5.7 s;
240
- after, 4 ms. With 30 slow loads at once the worker kept its 13 threads,
241
- RSS rose 131 -> 137 MB and `/up` stayed under 12 ms. Encodings pass
242
- through untouched. Without Rack hijack, and under Puma's own TLS (`ssl_bind`;
243
- its socket wrapper holds decrypted bytes `IO.select` can't see), the
244
- response is streamed from the Puma thread instead, as before: headers
245
- as soon as the server sends them, the body as Puma writes it. Behind
246
- Thruster, kamal-proxy or nginx the app sees plain HTTP/1.1 and the
247
- handoff applies; HTTP/2 ends at that proxy. It doesn't rewrite paths:
248
- the server itself serves under `/railwatch` (below). CSRF is the
249
- server's own (Origin check plus its token), so Rails' check is off for
250
- this controller, and so is inertia_rails' (its `XSRF-TOKEN` at
251
- `Path=/` shadowed the server's, refusing every write). inertia_rails'
252
- middleware would also answer every dashboard click with a 409 full
253
- reload, since the dashboard's Inertia version is the server's, not the
254
- app's; the proxy removes `X-Inertia` from the request once it has been
255
- forwarded, so the middleware leaves the response alone.
256
- Commenting, resolving, saving a view and changing a setting are tested
257
- through the proxy (`test/e2e/browser_writes.rb`, and by hand in Chromium).
258
- - **Live channel.** `/railwatch/cable` is a Rack hijack too; the browser's
259
- and the server's sockets are spliced by the same `IO.select` thread per
260
- app process (`Relay`), not two threads per socket: 30 open dashboards
261
- cost one thread. At most `max_live_connections` per process, counted
262
- apart from dashboard requests; past it the handshake gets 503 and the
263
- dashboard falls back to reloading.
264
- - **Trust.** `storage/railwatch/proxy_secret` (0600, generated) is the
265
- HMAC key. The header is `v1.<claims>.<HMAC-SHA256>` with
266
- `email, name, role, exp`; the server refuses a bad signature, an expired
267
- one, one valid for more than 5 minutes, and any role but admin/member
268
- (401, logged). It never falls back to "signed out". The server binds
269
- loopback only, so nothing outside the host can reach it unproxied.
270
-
271
- ## The server side (Rebulk/railwatch-rs)
272
-
273
- The server features this gem relies on are upstream, in Rebulk/railwatch-rs
274
- `main` from `ef87f72` (PR #16), and the dashboard's mount handling is part of
275
- the server's frontend. Every setting is off by default, so a self-hosted
276
- install is unchanged. Documented in railwatch-rs `docs/SELF-HOST.md`,
277
- "Running behind an app".
278
-
279
- - **`RAILWATCH_BASE_PATH`**: pages are served under a prefix (`/railwatch`)
280
- while `/ingest` and `/up` stay at the root, so the agent's URL doesn't
281
- change. Redirects, cookie paths, asset/icon/entry URLs, emails, MCP
282
- discovery and the Google callback all carry it.
283
- - **`RAILWATCH_TRUSTED_PROXY_SECRET_FILE`**: the server accepts an
284
- HMAC-signed `X-Railwatch-Proxy-Auth` header (email, name, admin/member
285
- role, `exp` at most 300 s ahead) from this gem's proxy as the signed-in
286
- user. The header is stripped from every request before any route sees it,
287
- even with the mode off; when on, an invalid one is a 401, never a
288
- fall-back. The proxy can't create or demote an owner.
289
- - **`RAILWATCH_STANDBY_RELAY`**: the server holding `serve.lock` also
290
- listens on `<data_dir>/serve.sock` (0600, peer uid checked); a second
291
- `serve` on the same data dir binds its own loopback port at once and
292
- relays to that socket until it gets the lock. This is what makes a
293
- two-container deploy overlap lose nothing (see "Deploys" below).
294
-
295
- **Why a base path, not rewriting in the proxy:** URLs are made in four
296
- places (Rust redirects, Inertia's 409 `X-Inertia-Location`, js-routes in
297
- the bundle, CSS/JS asset URLs) plus cookies and the cable URL. Rewriting
298
- means parsing HTML, JSON page props and JS chunks, and it breaks the first
299
- time the server adds a URL the proxy doesn't know about. With a base path
300
- the server says the right URL once and the proxy stays byte-transparent.
301
-
302
- ## Building
303
-
304
- ```sh
305
- script/build-server /path/to/railwatch-rs # railwatch-rs at or after ef87f72, frontend/dist built (bin/build, SKIP_CARGO=1)
306
- rake gem:all # pkg/: ruby + 4 platform gems (~10 MB each)
307
- ```
308
-
309
- Builds use the pinned `cargo-zigbuild` image from `bin/release`: static musl
310
- for Linux, and that image's MacOSX 11.3 SDK for both darwin targets. All
311
- four built here (2-3 min each, 4 jobs).
312
-
313
- **macOS: built natively, signed ad hoc, run in CI.** `.github/workflows/macos.yml`
314
- builds the frontend once on Linux, then on `macos-14` (arm64) and
315
- `macos-15-intel` (x86_64; GitHub retired the macos-13 runners) builds the
316
- server from the pinned railwatch-rs commit (`MACOSX_DEPLOYMENT_TARGET=11.0`, checked
317
- with `vtool`: minos 11.0), signs it `codesign -s -`, verifies the
318
- signature and the arch, and runs it: `--version`, `setup` in a temp dir,
319
- `serve`, `/up` and `/ingest/ping`, then a second `serve` on the same data
320
- dir that comes up as a standby and takes over when the first gets TERM.
321
- Then it builds the darwin platform gem, installs it, checks the installed
322
- binary's signature and runs it. Artifacts: the binary and the `.gem` per
323
- arch. The zigbuild cross-build in `script/build-server` still works for
324
- Linux; for darwin, use the workflow's artifacts (they are signed).
325
-
326
- ## Deploys and two processes
327
-
328
- - **Same host, same data dir** (two Pumas, or `phased-restart` overlap):
329
- the second app process finds the port already answered, starts its own
330
- server anyway (it waits on `serve.lock`) and logs "standby". Its agent
331
- reports to the first server, which owns the data. When the first app
332
- process stops, its server drains and exits, the standby takes the lock
333
- and the port (the log says "took over"). Measured: 10 + 10 requests
334
- during the overlap and 10 after, 30 of 30 stored; one server writes at
335
- any time.
336
- - **Two containers sharing a volume** (Kamal blue/green): each container
337
- has its own loopback, so the new container's agent can't reach the old
338
- container's server. The new container's server (`RAILWATCH_STANDBY_RELAY`,
339
- railwatch-rs `RAILWATCH_STANDBY_RELAY`) binds its own `127.0.0.1:28790` at once and splices
340
- every connection, byte for byte, to `storage/railwatch/serve.sock`, where
341
- the server holding `serve.lock` also listens. A Unix socket on the shared
342
- volume crosses network namespaces (same kernel, same inode). When the old
343
- container stops, its server drains and exits, the standby takes the lock
344
- and serves the same listener itself; connections in that gap retry the
345
- socket for up to 30 s. The log says "as a standby" then "took over".
346
-
347
- Why this mattered (measured, `test/overlap/`, 3 runs before the fix): the
348
- new container's first delivery was refused, the agent retained it and
349
- retried on its ladder, and every retained retry doubled its backpressure
350
- factor (1, 2, 4, 8). The sampler divides the request sample rate by that
351
- factor, so for the ~12 s until the old server exited the new container
352
- recorded 1 in 2, 1 in 4, then 1 in 8 of its requests. The dropped ones were
353
- never recorded at all; nothing that reached the agent's buffer was lost.
354
- 186, 184 and 197 of ~480 requests went unrecorded, every one at a factor
355
- of 2, 4 or 8, none at 1. With `RAILWATCH_BACKPRESSURE=false` the same
356
- overlap stored 476/476: the batches themselves all arrived on retry.
357
- Starting the server before Puma accepts requests (under `bin/rails s`)
358
- also removes the one refused delivery at boot that cost 5-9 requests.
359
-
360
- | handover, ~800 requests | served | stored once | lost |
361
- |---|---|---|---|
362
- | before, `docker stop` | 795 | 602 | 193 (new container: 186) |
363
- | before, SIGKILL | 793 | 582 | 211 |
364
- | after, `docker stop` | 795 | 795 | 0 |
365
- | after, SIGKILL of the old one | 789 | 771 | 18, all the old container's last second |
366
- | after, fresh `rails new` app (Rails 8.1, Solid Queue), `docker stop` | 865 | 865 | 0 |
367
- | after, fresh `rails new` app, SIGKILL of the old one | 845 | 828 | 17, the old container's last second |
368
-
369
- A SIGKILLed app loses what its agent had not flushed yet (up to
370
- `flush_interval`, here 1 s): the records were in that process's memory.
371
- The new container lost nothing in either run, and no record was stored
372
- twice. Volumes on two different hosts are not supported (flock and Unix
373
- sockets don't cross hosts; each host would need its own data dir, which
374
- splits the history).
375
-
376
- ## Cost (same app, same 1000 requests, single-mode Puma)
377
-
378
- | | idle RSS | RSS after 1000 req | CPU for 1000 req |
379
- |---|---|---|---|
380
- | this gem: `railwatch serve` | 12 MB | 51 MB | 0.15 s |
381
- | railwatch gem embedded: writer process | 87 MB | 138 MB | 0.08 s |
382
- | Puma itself (either way) | 126 MB | 162-166 MB | 3.2-3.8 s |
383
-
384
- The Rust server is a third of the Ruby writer's memory. The Ruby writer
385
- spends less CPU only because it writes rows and does no grouping,
386
- rollups, alerts or the dashboard. Rendering the dashboard costs the
387
- sidecar, not Puma (Puma only proxies), whereas the embedded dashboard
388
- renders inside Puma's workers.
389
-
390
- ## Limitations and TODOs
391
-
392
- - Dashboard connections close after each response (no keep-alive
393
- between the browser and the proxy for `/railwatch`). On loopback or
394
- behind a reverse proxy that costs nothing measurable; a browser talking
395
- straight to Puma over the internet opens a new TCP connection per
396
- dashboard request.
397
- - The cap is per process and checked before connecting, so a burst can
398
- pass it by as many requests as Puma has threads.
399
- - macOS binaries are ad-hoc signed only: fine for a gem installed with
400
- Bundler (RubyGems sets no quarantine flag). A notarized release needs an
401
- Apple Developer ID certificate in CI (`codesign -s "Developer ID
402
- Application: ..." --options runtime --timestamp`, then `notarytool
403
- submit --wait`); a bare executable can't be stapled, so Gatekeeper checks
404
- it online the first time it runs from a quarantined download.
405
- - One environment per data dir (above).
406
- - The account owner is a placeholder user with a random password nobody
407
- knows; the proxied users are admins/members. Transferring ownership
408
- works in Settings > Members.
409
- - Releases must keep building the platform gems from a published
410
- railwatch-rs commit: `RAILWATCH_RS_SHA` in
411
- `.github/workflows/macos.yml`, and the same commit for the Linux builds.
412
-
413
- ## License
414
-
415
- FSL-1.1-ALv2, the Functional Source License with an Apache 2.0 future
416
- license (LICENSE). Use it, change it and run it for your own apps freely;
417
- what it does not allow is a Competing Use: making Railwatch available to
418
- others in a commercial product or service that substitutes for Railwatch,
419
- offers substantially similar functionality, or substitutes for another
420
- product or service Rebulk offers using Railwatch (one that existed when that
421
- version was released). LICENSE has the exact terms. Each version
422
- released under FSL also becomes available under Apache-2.0 two years after
423
- its release. Releases up to and including 0.1.6 were published under
424
- AGPL-3.0-only and stay available under it alone; the Apache-2.0 grant does
425
- not apply to them.
426
-
427
- The platform gems contain the Railwatch server binary; NOTICE explains what
428
- that means for your app (nothing: it runs as a separate program) and where
429
- its source is.
11
+ `plugin :railwatch_server`, `RAILWATCH_SERVER_*`, `Railwatch::Server` and the
12
+ `railwatch_server:*` tasks keep working until railwatch-sidecar 1.0, with a warning.
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Bundler requires a gem by its name: load the renamed gem.
4
+ require "railwatch/sidecar"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: railwatch-server
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.9
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Rebulk
@@ -10,74 +10,36 @@ cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
- name: railwatch
13
+ name: railwatch-sidecar
14
14
  requirement: !ruby/object:Gem::Requirement
15
15
  requirements:
16
- - - ">="
16
+ - - "~>"
17
17
  - !ruby/object:Gem::Version
18
- version: '1.4'
18
+ version: '0.2'
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
- - - ">="
23
+ - - "~>"
24
24
  - !ruby/object:Gem::Version
25
- version: '1.4'
26
- - !ruby/object:Gem::Dependency
27
- name: railties
28
- requirement: !ruby/object:Gem::Requirement
29
- requirements:
30
- - - ">="
31
- - !ruby/object:Gem::Version
32
- version: '7.2'
33
- type: :runtime
34
- prerelease: false
35
- version_requirements: !ruby/object:Gem::Requirement
36
- requirements:
37
- - - ">="
38
- - !ruby/object:Gem::Version
39
- version: '7.2'
40
- - !ruby/object:Gem::Dependency
41
- name: inertia_rails
42
- requirement: !ruby/object:Gem::Requirement
43
- requirements:
44
- - - ">="
45
- - !ruby/object:Gem::Version
46
- version: '3.22'
47
- type: :development
48
- prerelease: false
49
- version_requirements: !ruby/object:Gem::Requirement
50
- requirements:
51
- - - ">="
52
- - !ruby/object:Gem::Version
53
- version: '3.22'
25
+ version: '0.2'
26
+ description: railwatch-server is now railwatch-sidecar (https://rubygems.org/gems/railwatch-sidecar).
27
+ Replace gem "railwatch-server" with gem "railwatch-sidecar" in your Gemfile; every
28
+ old name keeps working until railwatch-sidecar 1.0.
54
29
  executables: []
55
30
  extensions: []
56
31
  extra_rdoc_files: []
57
32
  files:
58
33
  - LICENSE
59
- - NOTICE
60
34
  - README.md
61
- - app/controllers/railwatch/server/proxy_controller.rb
62
- - lib/puma/plugin/railwatch_server.rb
63
- - lib/railwatch/server.rb
64
- - lib/railwatch/server/binary.rb
65
- - lib/railwatch/server/configuration.rb
66
- - lib/railwatch/server/data_dir.rb
67
- - lib/railwatch/server/engine.rb
68
- - lib/railwatch/server/process.rb
69
- - lib/railwatch/server/proxy_auth.rb
70
- - lib/railwatch/server/proxy_handoff.rb
71
- - lib/railwatch/server/relay.rb
72
- - lib/railwatch/server/settings.rb
73
- - lib/railwatch/server/version.rb
74
- - lib/tasks/railwatch_server.rake
75
- homepage: https://github.com/Rebulk/railwatch-server
35
+ - lib/railwatch-server.rb
36
+ homepage: https://github.com/Rebulk/railwatch-sidecar
76
37
  licenses:
77
38
  - FSL-1.1-ALv2
78
39
  metadata:
79
- source_code_uri: https://github.com/Rebulk/railwatch-server
80
- railwatch_rs_source: https://github.com/Rebulk/railwatch-rs
40
+ source_code_uri: https://github.com/Rebulk/railwatch-sidecar
41
+ post_install_message: 'railwatch-server is now railwatch-sidecar: change gem "railwatch-server"
42
+ to gem "railwatch-sidecar" in your Gemfile.'
81
43
  rdoc_options: []
82
44
  require_paths:
83
45
  - lib
@@ -92,8 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
92
54
  - !ruby/object:Gem::Version
93
55
  version: '0'
94
56
  requirements: []
95
- rubygems_version: 4.0.16
57
+ rubygems_version: 3.6.9
96
58
  specification_version: 4
97
- summary: 'The Railwatch server, bundled: the full Railwatch dashboard at /railwatch
98
- in your Rails app, run as its own process'
59
+ summary: 'Renamed: use railwatch-sidecar. This release only depends on it.'
99
60
  test_files: []
data/NOTICE DELETED
@@ -1,25 +0,0 @@
1
- railwatch-server bundles the Railwatch server.
2
-
3
- The platform gems of railwatch-server (x86_64-linux, aarch64-linux,
4
- x86_64-darwin, arm64-darwin) contain exe/<platform>/railwatch, a compiled
5
- build of Railwatch (railwatch-rs), https://github.com/Rebulk/railwatch-rs,
6
- which is under the Functional Source License, Version 1.1, ALv2 Future
7
- License (FSL-1.1-ALv2). This gem's own Ruby code is under the same license;
8
- see LICENSE.
9
-
10
- The source of the bundled binary is the railwatch-rs commit
11
- named in lib/railwatch/server/version.rb (RAILWATCH_RS), unmodified. The
12
- running server also links to its source on every response (the Link header and /source).
13
- Third-party code compiled into the binary keeps its own licenses, listed in
14
- railwatch-rs's THIRD-PARTY-LICENSES.
15
-
16
- Running this gem in your application does not make your application a
17
- derivative of Railwatch: the server is a separate program, started as its
18
- own process and spoken to over HTTP. You may run it, and change it, to
19
- monitor your own applications; the license does not allow offering it, or
20
- something substantially like it, to others as a commercial product or
21
- service.
22
-
23
- The railwatch gem (https://github.com/Rebulk/railwatch), the agent that
24
- reports your app's telemetry, is a separate gem under the MIT license. This
25
- gem depends on it; it is not part of this gem.