feat(dashboard): add a console client for the observability proxy

The observability proxy serves metrics and logs under Kubernetes-shaped
paths but answers in native Prometheus JSON and VictoriaLogs NDJSON, so
the typed K8sClient methods cannot read it. A raw fetch on the client
keeps the same credentials and 401 handling the rest of the console
uses, and the proxy module maps each documented status to its own
error kind so a cluster without the proxy (404) can be told apart from
a denied request or a store that is down.

Assisted-by: LLM
Signed-off-by: ZverGuy <maximbel2003@gmail.com>
This commit is contained in:
ZverGuy committed 2026-11-04 05:25:58 +07:00
1 parent 4087218a02
commit e96ceedd7e
4 files changed
+447

No files matched your search

@@ -0,0 +1,47 @@
import { describe, it, expect, vi, afterEach } from "vitest"
import { K8sClient } from "@cozystack/k8s-client"
afterEach(() => {
vi.unstubAllGlobals()
vi.restoreAllMocks()
})
describe("K8sClient.raw", () => {
it("returns the response untouched, including a non-2xx one", async () => {
const res = new Response("not found", { status: 404 })
vi.stubGlobal("fetch", vi.fn(async () => res))
const client = new K8sClient()
await expect(client.raw("/x")).resolves.toBe(res)
})
it("prefixes the base URL and attaches the bearer token", async () => {
const fetchMock = vi.fn(async () => new Response("{}"))
vi.stubGlobal("fetch", fetchMock)
const client = new K8sClient({ baseUrl: "/base", getToken: async () => "t0k" })
await client.raw("/apis/x", { headers: { Accept: "application/json" } })
const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit]
expect(url).toBe("/base/apis/x")
expect(init.headers).toEqual({ Accept: "application/json", Authorization: "Bearer t0k" })
})
it("routes a 401 through the client's unauthorized handler", async () => {
const onUnauthorized = vi.fn()
vi.stubGlobal("fetch", vi.fn(async () => new Response("", { status: 401 })))
const client = new K8sClient({ onUnauthorized })
const res = await client.raw("/x")
expect(res.status).toBe(401)
expect(onUnauthorized).toHaveBeenCalledTimes(1)
})
it("does not swallow a network failure", async () => {
vi.stubGlobal("fetch", vi.fn(async () => { throw new TypeError("offline") }))
const client = new K8sClient()
await expect(client.raw("/x")).rejects.toThrow("offline")
})
})
@@ -0,0 +1,179 @@
import { describe, it, expect, vi } from "vitest"
import { K8sClient } from "@cozystack/k8s-client"
import {
ProxyError,
errorKindForStatus,
fieldValues,
logsRoot,
metricsRoot,
queryLogs,
queryRange,
tailLogs,
} from "./proxy.ts"
const app = { namespace: "tenant-a", plural: "postgreses", name: "db" }
const ns = { namespace: "tenant-a" }
function clientReturning(...responses: Response[]) {
const client = new K8sClient({ onUnauthorized: () => {} })
const raw = vi.spyOn(client, "raw")
for (const r of responses) raw.mockResolvedValueOnce(r)
return { client, raw }
}
function calledUrl(raw: ReturnType<typeof clientReturning>["raw"], call = 0): URL {
return new URL(raw.mock.calls[call][0], "http://x")
}
describe("roots", () => {
it("builds the application roots under apps.cozystack.io", () => {
expect(metricsRoot(app)).toBe("/apis/apps.cozystack.io/v1alpha1/namespaces/tenant-a/postgreses/db/metrics/")
expect(logsRoot(app)).toBe("/apis/apps.cozystack.io/v1alpha1/namespaces/tenant-a/postgreses/db/log/")
})
it("builds the namespace roots under cozystack.io", () => {
expect(metricsRoot(ns)).toBe("/apis/cozystack.io/v1alpha1/namespaces/tenant-a/metrics/")
expect(logsRoot(ns)).toBe("/apis/cozystack.io/v1alpha1/namespaces/tenant-a/logs/")
})
})
describe("errorKindForStatus", () => {
it.each([
[400, "bad-request"],
[401, "unauthorized"],
[403, "forbidden"],
[404, "not-available"],
[422, "limit"],
[429, "rate-limited"],
[502, "store-unreachable"],
[503, "unavailable"],
[504, "timeout"],
[500, "unknown"],
])("maps %i to %s", (status, kind) => {
expect(errorKindForStatus(status)).toBe(kind)
})
})
describe("queryRange", () => {
it("GETs query_range under the root and returns the matrix", async () => {
const body = { status: "success", data: { resultType: "matrix", result: [{ metric: { pod: "p" }, values: [[1, "2"]] }] } }
const { client, raw } = clientReturning(Response.json(body))
const result = await queryRange(client, metricsRoot(app), { query: "up", start: 10, end: 20, step: 5 })
const url = calledUrl(raw)
expect(url.pathname).toBe(`${metricsRoot(app)}api/v1/query_range`)
expect(Object.fromEntries(url.searchParams)).toEqual({ query: "up", start: "10", end: "20", step: "5" })
expect(result).toEqual(body.data.result)
})
it("throws a ProxyError carrying the Prometheus error text", async () => {
const { client } = clientReturning(
Response.json({ status: "error", error: "range too long" }, { status: 422 }),
)
const err = await queryRange(client, metricsRoot(app), { query: "up", start: 0, end: 1, step: 1 }).catch((e) => e)
expect(err).toBeInstanceOf(ProxyError)
expect(err).toMatchObject({ kind: "limit", status: 422, message: "range too long" })
})
it("reports a fetch failure as a network error", async () => {
const client = new K8sClient()
vi.spyOn(client, "raw").mockRejectedValue(new TypeError("offline"))
const err = await queryRange(client, metricsRoot(app), { query: "up", start: 0, end: 1, step: 1 }).catch((e) => e)
expect(err).toMatchObject({ kind: "network" })
})
})
describe("queryLogs", () => {
it("parses NDJSON lines and sorts them by _time ascending", async () => {
const ndjson = [
JSON.stringify({ _time: "2026-11-04T10:00:02Z", _msg: "b" }),
"",
JSON.stringify({ _time: "2026-11-04T10:00:01Z", _msg: "a" }),
].join("\n")
const { client, raw } = clientReturning(new Response(ndjson))
const entries = await queryLogs(client, logsRoot(ns), { query: "*", start: "s", end: "e", limit: 100 })
expect(calledUrl(raw).pathname).toBe(`${logsRoot(ns)}select/logsql/query`)
expect(Object.fromEntries(calledUrl(raw).searchParams)).toEqual({ query: "*", start: "s", end: "e", limit: "100" })
expect(entries.map((e) => e._msg)).toEqual(["a", "b"])
})
it("keeps a plain-text error body as the message", async () => {
const { client } = clientReturning(new Response("cannot parse query", { status: 400 }))
const err = await queryLogs(client, logsRoot(ns), { query: "(", start: "s", end: "e", limit: 1 }).catch((e) => e)
expect(err).toMatchObject({ kind: "bad-request", message: "cannot parse query" })
})
})
describe("fieldValues", () => {
it("uses stream_field_values for stream fields and returns the values", async () => {
const { client, raw } = clientReturning(
Response.json({ values: [{ value: "pod-b", hits: 1 }, { value: "pod-a", hits: 9 }] }),
)
const values = await fieldValues(client, logsRoot(app), {
field: "kubernetes_pod_name",
stream: true,
query: "*",
start: "s",
end: "e",
})
expect(calledUrl(raw).pathname).toBe(`${logsRoot(app)}select/logsql/stream_field_values`)
expect(calledUrl(raw).searchParams.get("field")).toBe("kubernetes_pod_name")
expect(values).toEqual(["pod-a", "pod-b"])
})
it("uses field_values for other fields", async () => {
const { client, raw } = clientReturning(Response.json({ values: [] }))
await fieldValues(client, logsRoot(app), { field: "level", stream: false, query: "*", start: "s", end: "e" })
expect(calledUrl(raw).pathname).toBe(`${logsRoot(app)}select/logsql/field_values`)
})
})
describe("tailLogs", () => {
it("delivers every line as it arrives, including one split across chunks", async () => {
const enc = new TextEncoder()
const chunks = ['{"_time":"t1","_msg":"a"}\n{"_ti', 'me":"t2","_msg":"b"}\n']
const body = new ReadableStream<Uint8Array>({
start(c) {
for (const ch of chunks) c.enqueue(enc.encode(ch))
c.close()
},
})
const { client, raw } = clientReturning(new Response(body))
const seen: string[] = []
await tailLogs(client, logsRoot(ns), { query: "*", since: "t0" }, (e) => seen.push(e._msg))
expect(calledUrl(raw).pathname).toBe(`${logsRoot(ns)}select/logsql/tail`)
expect(calledUrl(raw).searchParams.get("since")).toBe("t0")
expect(seen).toEqual(["a", "b"])
})
it("omits since on the first connect", async () => {
const { client, raw } = clientReturning(new Response(""))
await tailLogs(client, logsRoot(ns), { query: "*" }, () => {})
expect(calledUrl(raw).searchParams.has("since")).toBe(false)
})
it("throws a ProxyError when the tail is refused", async () => {
const { client } = clientReturning(new Response("", { status: 403 }))
const err = await tailLogs(client, logsRoot(ns), { query: "*" }, () => {}).catch((e) => e)
expect(err).toMatchObject({ kind: "forbidden" })
})
})
@@ -0,0 +1,203 @@
import type { K8sClient } from "@cozystack/k8s-client"
export type ObservabilityScope =
| { namespace: string }
| { namespace: string; plural: string; name: string }
function appBase(scope: ObservabilityScope): string | null {
if (!("plural" in scope)) return null
return `/apis/apps.cozystack.io/v1alpha1/namespaces/${scope.namespace}/${scope.plural}/${scope.name}`
}
export function metricsRoot(scope: ObservabilityScope): string {
const app = appBase(scope)
return app ? `${app}/metrics/` : `/apis/cozystack.io/v1alpha1/namespaces/${scope.namespace}/metrics/`
}
export function logsRoot(scope: ObservabilityScope): string {
const app = appBase(scope)
return app ? `${app}/log/` : `/apis/cozystack.io/v1alpha1/namespaces/${scope.namespace}/logs/`
}
export type ProxyErrorKind =
| "bad-request"
| "unauthorized"
| "forbidden"
| "not-available"
| "limit"
| "rate-limited"
| "store-unreachable"
| "unavailable"
| "timeout"
| "network"
| "unknown"
const KIND_BY_STATUS: Record<number, ProxyErrorKind> = {
400: "bad-request",
401: "unauthorized",
403: "forbidden",
404: "not-available",
422: "limit",
429: "rate-limited",
502: "store-unreachable",
503: "unavailable",
504: "timeout",
}
export function errorKindForStatus(status: number): ProxyErrorKind {
return KIND_BY_STATUS[status] ?? "unknown"
}
export class ProxyError extends Error {
kind: ProxyErrorKind
status: number
constructor(kind: ProxyErrorKind, status: number, message: string) {
super(message)
this.name = "ProxyError"
this.kind = kind
this.status = status
}
}
// Prometheus answers {"error": "..."}, VictoriaLogs and nginx answer plain text.
function errorMessage(text: string, status: number): string {
try {
const parsed: unknown = JSON.parse(text)
if (parsed && typeof parsed === "object" && "error" in parsed && typeof parsed.error === "string") {
return parsed.error
}
} catch {
// not JSON
}
const trimmed = text.trim()
return trimmed && trimmed.length < 300 && !trimmed.startsWith("<") ? trimmed : `Server returned ${status}`
}
async function proxyGet(
client: K8sClient,
path: string,
params: Record<string, string | number | undefined>,
signal?: AbortSignal,
): Promise<Response> {
const search = new URLSearchParams()
for (const [k, v] of Object.entries(params)) if (v !== undefined) search.set(k, String(v))
let res: Response
try {
res = await client.raw(`${path}?${search}`, { signal })
} catch (err) {
if (signal?.aborted) throw err
throw new ProxyError("network", 0, "Unable to connect to the server")
}
if (!res.ok) {
const text = await res.text().catch(() => "")
throw new ProxyError(errorKindForStatus(res.status), res.status, errorMessage(text, res.status))
}
return res
}
export interface PromSeries {
metric: Record<string, string>
values: [number, string][]
}
export interface RangeParams {
query: string
start: number
end: number
step: number
}
export async function queryRange(
client: K8sClient,
root: string,
params: RangeParams,
signal?: AbortSignal,
): Promise<PromSeries[]> {
const res = await proxyGet(client, `${root}api/v1/query_range`, { ...params }, signal)
const body = (await res.json()) as { data?: { result?: PromSeries[] } }
return body.data?.result ?? []
}
export interface LogEntry {
_time: string
_msg: string
_stream_id?: string
[field: string]: string | undefined
}
function parseLine(line: string): LogEntry | null {
if (!line.trim()) return null
try {
const value: unknown = JSON.parse(line)
if (value && typeof value === "object" && "_time" in value) return value as LogEntry
} catch {
// a torn or non-JSON line carries nothing to show
}
return null
}
export interface LogsQueryParams {
query: string
start: string
end: string
limit: number
}
export async function queryLogs(
client: K8sClient,
root: string,
params: LogsQueryParams,
signal?: AbortSignal,
): Promise<LogEntry[]> {
const res = await proxyGet(client, `${root}select/logsql/query`, { ...params }, signal)
const entries = (await res.text()).split("\n").map(parseLine).filter((e) => e !== null)
return entries.sort((a, b) => (a._time < b._time ? -1 : a._time > b._time ? 1 : 0))
}
export interface FieldValuesParams {
field: string
stream: boolean
query: string
start: string
end: string
}
export async function fieldValues(
client: K8sClient,
root: string,
{ stream, ...params }: FieldValuesParams,
signal?: AbortSignal,
): Promise<string[]> {
const endpoint = stream ? "stream_field_values" : "field_values"
const res = await proxyGet(client, `${root}select/logsql/${endpoint}`, { ...params }, signal)
const body = (await res.json()) as { values?: { value: string }[] }
return (body.values ?? []).map((v) => v.value).sort()
}
export async function tailLogs(
client: K8sClient,
root: string,
params: { query: string; since?: string },
onEntry: (entry: LogEntry) => void,
signal?: AbortSignal,
): Promise<void> {
const res = await proxyGet(client, `${root}select/logsql/tail`, params, signal)
if (!res.body) return
const reader = res.body.getReader()
const decoder = new TextDecoder()
let buffer = ""
for (;;) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
const lines = buffer.split("\n")
buffer = lines.pop() ?? ""
for (const line of lines) {
const entry = parseLine(line)
if (entry) onEntry(entry)
}
}
const last = parseLine(buffer)
if (last) onEntry(last)
}
@@ -241,6 +241,24 @@ export class K8sClient {
})
}
/**
* Fetch a same-origin path with the client's credentials and 401 handling,
* leaving status and body to the caller. For endpoints that do not speak
* Kubernetes JSON, such as the observability proxy's streamed NDJSON.
*/
async raw(path: string, init?: RequestInit): Promise<Response> {
const headers: Record<string, string> = {
...(init?.headers as Record<string, string>),
}
if (this.getToken) {
headers["Authorization"] = `Bearer ${await this.getToken()}`
}
const res = await fetch(`${this.baseUrl}${path}`, { ...init, headers })
if (res.status === 401) this.handleUnauthorized()
else if (res.ok) this.unauthorizedHandled = false
return res
}
getApiGroups(): Promise<APIGroupList> {
return this.request<APIGroupList>("/apis")
}