SleeuumLedger.java
connector/java/com/mearvk/sleela/connector/http/SleeuumLedger.java · 364 line(s) · java
package com.mearvk.sleela.connector.http;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
/**
* Sleeuum™ โ server-side packet ledger for the SLeeLa HTTP 3.0 module.
*
* <p>The Java counterpart of {@code http-3.0/sleeuum.py}. It keeps track of the
* HTTP 3.0 / HTTP 2.0+ packets that {@link SleelaH3Servlet} handles โ with their
* <b>dates</b> (ISO-8601 UTC) and their <b>numbers</b> (a monotonic sequence, the
* H3 NONCE / DIGEST / request-id / status, byte counts, and the basket numerals
* carried in each packet). It emits JSON that conforms to
* {@code http-3.0/sleeuum.schema.json}.</p>
*
* <p>Observe-only, exactly like the client module: the ledger never alters a
* packet or an integrity field; it records the H3 status precisely as the
* pipeline returned it. Thread-safe for concurrent servlet requests.</p>
*/
public final class SleeuumLedger {
/** Trademark rendering (unicode). ASCII fallback: {@code Sleeuum(TM)}. */
public static final String SLEEUUM_TM = "Sleeuum\u2122";
private final String client;
/** Cap on retained per-packet records; older ones are dropped (rolling window).
* Rolled-up stats still count every packet ever seen. */
private static final int MAX_RECORDS = 10_000;
private final AtomicLong seq = new AtomicLong(0);
private final java.util.ArrayDeque<Map<String, Object>> records = new java.util.ArrayDeque<>();
// Rolled-up numbers (guarded by `this`). totalPackets counts ALL packets ever
// observed, independent of the retained-records window.
private long totalPackets;
private long sent, received, requests, responses, totalPayload, totalWire;
private final Map<String, Long> byCarrier = new LinkedHashMap<>();
private final Map<String, Long> byStatus = new LinkedHashMap<>();
private String firstSeen, lastSeen;
public SleeuumLedger(String client) {
this.client = client == null ? "sleela-h3" : client;
}
/** Record a request packet the server received (raw H3 envelope wire bytes). */
public synchronized void trackRequest(byte[] h3Wire, String carrier, int wireBytes) {
Map<String, Object> r = base("received", carrier, "request", h3Wire, wireBytes);
H3Text parsed = parseRequestText(h3Wire);
if (parsed != null) {
r.put("service_id", parsed.serviceId);
r.put("op_id", parsed.opId);
r.put("request_id", parsed.requestId);
r.put("nonce", parsed.nonce);
r.put("digest", parsed.digest);
r.put("intactx", parsed.intactx);
r.put("payload_bytes", parsed.payloadLen);
r.put("numerals", parsed.numerals);
}
requests++;
commit(r);
}
/** Record a response packet the server sent (raw H3R response wire bytes). */
public synchronized void trackResponse(byte[] h3rWire, String carrier, int wireBytes) {
Map<String, Object> r = base("sent", carrier, "response", h3rWire, wireBytes);
H3Resp parsed = parseResponseText(h3rWire);
if (parsed != null) {
r.put("request_id", parsed.requestId);
r.put("status", parsed.status);
r.put("status_name", statusName(parsed.status));
r.put("payload_bytes", parsed.resultLen);
byStatus.merge(statusName(parsed.status), 1L, Long::sum);
}
responses++;
commit(r);
}
/** Serialize the ledger to schema-conforming JSON (dates + numbers + packets). */
public synchronized String toJson() {
StringBuilder sb = new StringBuilder(256 + records.size() * 128);
sb.append('{');
kv(sb, "module", SLEEUUM_TM).append(',');
kv(sb, "trademark", SLEEUUM_TM).append(',');
kv(sb, "client", client).append(',');
kv(sb, "generated", nowIso()).append(',');
sb.append("\"stats\":").append(statsJson()).append(',');
sb.append("\"packets\":[");
boolean first = true;
for (Map<String, Object> rec : records) {
if (!first) sb.append(',');
sb.append(mapJson(rec));
first = false;
}
sb.append("]}");
return sb.toString();
}
/** Total packets ever observed (not just those still retained in the window). */
public synchronized long count() { return totalPackets; }
/** Number of per-packet records currently retained (<= MAX_RECORDS). */
public synchronized long retained() { return records.size(); }
// ------------------------------------------------------------------ internals
private Map<String, Object> base(String direction, String carrier, String kind,
byte[] wire, int wireBytes) {
String at = nowIso();
Map<String, Object> r = new LinkedHashMap<>();
r.put("seq", seq.incrementAndGet());
r.put("at", at);
r.put("direction", direction);
r.put("carrier", carrier == null ? "h3-raw" : carrier);
r.put("kind", kind);
r.put("wire_form", wireFormOf(wire));
r.put("payload_bytes", 0);
r.put("wire_bytes", wireBytes);
return r;
}
private void commit(Map<String, Object> r) {
records.addLast(r);
// Bound memory: keep only the most recent MAX_RECORDS packets. Stats
// below already counted this packet, so trimming never loses a count.
while (records.size() > MAX_RECORDS) {
records.pollFirst();
}
totalPackets++;
String carrier = (String) r.get("carrier");
byCarrier.merge(carrier, 1L, Long::sum);
if ("sent".equals(r.get("direction"))) sent++; else received++;
totalPayload += ((Number) r.getOrDefault("payload_bytes", 0)).longValue();
totalWire += ((Number) r.getOrDefault("wire_bytes", 0)).longValue();
String at = (String) r.get("at");
if (firstSeen == null) firstSeen = at;
lastSeen = at;
}
private String statsJson() {
StringBuilder sb = new StringBuilder(160);
sb.append('{');
sb.append("\"packets\":").append(totalPackets).append(',');
sb.append("\"retained\":").append(records.size()).append(',');
sb.append("\"sent\":").append(sent).append(',');
sb.append("\"received\":").append(received).append(',');
sb.append("\"requests\":").append(requests).append(',');
sb.append("\"responses\":").append(responses).append(',');
sb.append("\"total_payload_bytes\":").append(totalPayload).append(',');
sb.append("\"total_wire_bytes\":").append(totalWire).append(',');
sb.append("\"by_carrier\":").append(countMapJson(byCarrier)).append(',');
sb.append("\"by_status\":").append(countMapJson(byStatus)).append(',');
sb.append("\"first_seen\":").append(firstSeen == null ? "null" : quote(firstSeen)).append(',');
sb.append("\"last_seen\":").append(lastSeen == null ? "null" : quote(lastSeen)).append(',');
sb.append("\"duration_seconds\":").append(durationSeconds());
sb.append('}');
return sb.toString();
}
private double durationSeconds() {
if (firstSeen == null || lastSeen == null) return 0.0;
try {
return (Instant.parse(lastSeen).toEpochMilli() - Instant.parse(firstSeen).toEpochMilli()) / 1000.0;
} catch (RuntimeException e) {
return 0.0;
}
}
private static String nowIso() {
// Instant.toString() is ISO-8601 UTC with a trailing 'Z' (schema pattern).
return Instant.now().toString();
}
private static String wireFormOf(byte[] wire) {
if (wire != null && wire.length >= 3 && wire[0] == 'H' && wire[1] == '3') {
// "H3 " -> textual envelope; "H3R" -> textual response; both are text.
return "text";
}
return "binary";
}
// ---- H3 textual parsers (mirror Envelope/Response.unpack_text) ------------
private static final class H3Text {
long serviceId, opId, requestId, nonce, digest, intactx;
int payloadLen;
List<Integer> numerals = new ArrayList<>();
}
private static final class H3Resp {
int status;
long requestId;
int resultLen;
}
/**
* Parse a textual H3 request line:
* {@code H3 <ver> <flags> <sid> <oid> <rid> <nonce> <digest> <intactx> <basket-hex> <plen>:<payload>}
*/
private static H3Text parseRequestText(byte[] wire) {
int colon = indexOf(wire, (byte) ':');
if (colon < 0) return null;
String head = new String(wire, 0, colon, StandardCharsets.US_ASCII);
String[] p = head.split(" ");
if (p.length != 11 || !"H3".equals(p[0])) return null;
try {
H3Text h = new H3Text();
h.serviceId = Long.parseLong(p[3]);
h.opId = Long.parseLong(p[4]);
h.requestId = Long.parseLong(p[5]);
h.nonce = Long.parseLong(p[6]);
h.digest = Long.parseUnsignedLong(p[7]);
h.intactx = Long.parseUnsignedLong(p[8]);
h.payloadLen = Integer.parseInt(p[10]);
h.numerals = basketNumerals(p[9]);
return h;
} catch (RuntimeException e) {
return null;
}
}
/** Parse a textual H3 response line: {@code H3R <status> <rid> <rlen>:<result>}. */
private static H3Resp parseResponseText(byte[] wire) {
int colon = indexOf(wire, (byte) ':');
if (colon < 0) return null;
String head = new String(wire, 0, colon, StandardCharsets.US_ASCII);
String[] p = head.split(" ");
if (p.length != 4 || !"H3R".equals(p[0])) return null;
try {
H3Resp r = new H3Resp();
r.status = Integer.parseInt(p[1]);
r.requestId = Long.parseLong(p[2]);
r.resultLen = Integer.parseInt(p[3]);
return r;
} catch (RuntimeException e) {
return null;
}
}
/**
* Extract basket numerals (atomic-number item ids) from the basket hex token.
* Canonical block: iso(2) + count(2), then per item number(4) + value(8),
* big-endian โ matches basket_serialize() / http3_basket_serialize().
*/
private static List<Integer> basketNumerals(String basketHex) {
List<Integer> out = new ArrayList<>();
try {
byte[] b = hexToBytes(basketHex);
if (b.length < 4) return out;
int count = ((b[2] & 0xFF) << 8) | (b[3] & 0xFF);
int off = 4;
for (int i = 0; i < count && off + 12 <= b.length; i++, off += 12) {
int number = ((b[off] & 0xFF) << 24) | ((b[off + 1] & 0xFF) << 16)
| ((b[off + 2] & 0xFF) << 8) | (b[off + 3] & 0xFF);
out.add(number);
}
} catch (RuntimeException e) {
// leave numerals empty on any parse issue
}
return out;
}
private static String statusName(int status) {
switch (status) {
case 0: return "OK";
case 1: return "APP_ERROR";
case 2: return "UNKNOWN_SERVICE";
case 3: return "UNKNOWN_OPERATION";
case 4: return "BAD_ENVELOPE";
case 5: return "TOO_LARGE";
case 6: return "RETRY_DENIED";
case 7: return "BAD_DIGEST";
case 8: return "TAMPERED";
case 9: return "REPLAYED";
default: return "APP_ERROR";
}
}
// ---- small helpers --------------------------------------------------------
private static int indexOf(byte[] a, byte target) {
for (int i = 0; i < a.length; i++) if (a[i] == target) return i;
return -1;
}
private static byte[] hexToBytes(String hex) {
int n = hex.length() / 2;
byte[] out = new byte[n];
for (int i = 0; i < n; i++) {
out[i] = (byte) Integer.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
}
return out;
}
private static StringBuilder kv(StringBuilder sb, String k, String v) {
return sb.append(quote(k)).append(':').append(quote(v));
}
private static String countMapJson(Map<String, Long> m) {
StringBuilder sb = new StringBuilder();
sb.append('{');
boolean first = true;
for (Map.Entry<String, Long> e : m.entrySet()) {
if (!first) sb.append(',');
sb.append(quote(e.getKey())).append(':').append(e.getValue());
first = false;
}
return sb.append('}').toString();
}
@SuppressWarnings("unchecked")
private static String mapJson(Map<String, Object> m) {
StringBuilder sb = new StringBuilder();
sb.append('{');
boolean first = true;
for (Map.Entry<String, Object> e : m.entrySet()) {
if (!first) sb.append(',');
sb.append(quote(e.getKey())).append(':');
Object v = e.getValue();
if (v instanceof String) {
sb.append(quote((String) v));
} else if (v instanceof List) {
sb.append('[');
List<Object> list = (List<Object>) v;
for (int i = 0; i < list.size(); i++) {
if (i > 0) sb.append(',');
sb.append(String.valueOf(list.get(i)));
}
sb.append(']');
} else {
sb.append(String.valueOf(v)); // numbers
}
first = false;
}
return sb.append('}').toString();
}
private static String quote(String s) {
StringBuilder sb = new StringBuilder(s.length() + 2);
sb.append('"');
for (int i = 0; i < s.length(); i++) {
char c = s.charAt(i);
switch (c) {
case '"': sb.append("\\\""); break;
case '\\': sb.append("\\\\"); break;
case '\n': sb.append("\\n"); break;
case '\r': sb.append("\\r"); break;
case '\t': sb.append("\\t"); break;
default:
if (c < 0x20 || c > 0x7E) {
sb.append(String.format("\\u%04x", (int) c));
} else {
sb.append(c);
}
}
}
return sb.append('"').toString();
}
}