|
| 1 | +/* |
| 2 | + * Copyright (c) 2026 htjulia <htjulia1@gmail.com> |
| 3 | + * |
| 4 | + * This Source Code Form is subject to the terms of the Mozilla Public |
| 5 | + * License, v. 2.0. If a copy of the MPL was not distributed with this |
| 6 | + * file, You can obtain one at https://mozilla.org/MPL/2.0/. |
| 7 | + */ |
| 8 | + |
| 9 | +package org.htcom.protean.web; |
| 10 | + |
| 11 | +/** |
| 12 | + * Connection acknowledgement: the first frame of every {@code /platform/traces/stream} connection |
| 13 | + * ({@code event: ready}). It exists because "the stream is open" and "the server is actually running" |
| 14 | + * are indistinguishable to a client on a quiet platform — nothing else arrives until traffic does. |
| 15 | + * |
| 16 | + * <p>This is an ack, not a data frame. It carries only values a client must know <em>once, at connect |
| 17 | + * time</em> and cannot derive from the stream afterwards; anything that changes on a schedule belongs to |
| 18 | + * the {@code metrics}/{@code modules}/{@code summary} frames instead. |
| 19 | + * |
| 20 | + * @param platform implementation identifier, constant {@code "protean"}. Present so a console that |
| 21 | + * watches several implementations does not have to read a bare version number and |
| 22 | + * guess whose it is. Display/diagnostics only — clients must not branch behaviour on it. |
| 23 | + * @param platformVersion this library's version, read from the jar manifest ({@code Implementation-Version}). |
| 24 | + * {@code null} when running from a layout that has no manifest (exploded classes: tests, |
| 25 | + * IDE runs) — the version is genuinely unknown there, and a placeholder string would be |
| 26 | + * a fabricated answer to "which version am I talking to". |
| 27 | + * @param tracesEnabled {@code protean.trace.enabled}: distinguishes "recording is off" from "recording is on |
| 28 | + * but nothing has happened yet", which an empty stream cannot. |
| 29 | + * @param metricsEnabled {@code protean.trace.metrics.enabled}: same distinction for the {@code metrics} frame. |
| 30 | + * @param buffered how many rows the {@code trace} frame that follows this one carries — <em>not</em> how |
| 31 | + * many the ring holds. The two differ whenever the ring is larger than the replay cap, and |
| 32 | + * announcing a count while withholding the rows is worse than announcing neither. |
| 33 | + * @param tickMs the push period, so a client's silence watchdog has a contract to size itself against |
| 34 | + * instead of assuming one. |
| 35 | + * @param capacity {@code protean.trace.capacity} <em>as of this connection</em>, letting a client say |
| 36 | + * "nothing older than this is on the server". It is a live key, so a later change does not |
| 37 | + * reach an already-connected client; the value is re-sent on reconnect. |
| 38 | + */ |
| 39 | +public record StreamReady( |
| 40 | + String platform, |
| 41 | + String platformVersion, |
| 42 | + boolean tracesEnabled, |
| 43 | + boolean metricsEnabled, |
| 44 | + int buffered, |
| 45 | + long tickMs, |
| 46 | + int capacity |
| 47 | +) { |
| 48 | + |
| 49 | + private static final String PLATFORM = "protean"; |
| 50 | + |
| 51 | + /** Resolved once: a jar manifest cannot change while the JVM runs. */ |
| 52 | + private static final String VERSION = version(); |
| 53 | + |
| 54 | + private static String version() { |
| 55 | + Package pkg = StreamReady.class.getPackage(); |
| 56 | + return pkg == null ? null : pkg.getImplementationVersion(); |
| 57 | + } |
| 58 | + |
| 59 | + /** Ack for a connection that is about to replay {@code buffered} trace rows. */ |
| 60 | + public static StreamReady of(boolean tracesEnabled, boolean metricsEnabled, int buffered, long tickMs, int capacity) { |
| 61 | + return new StreamReady(PLATFORM, VERSION, tracesEnabled, metricsEnabled, buffered, tickMs, capacity); |
| 62 | + } |
| 63 | +} |
0 commit comments