@empyria/restate 0.1.14 → 0.1.16

package/lib/Admin.js

@@ -127,6 +127,35 @@ export async function listServices({ restateAdminURL }) {
 	return data.services // Array of { name, handlers, ty, deployment_id, ... }
 }
 
+/**
+ * Runs a raw SQL query against Restate's own introspection API (`POST {adminURL}/query`) — the
+ * `sys_invocation`/`state`/`sys_promise`/... tables Restate exposes specifically so operators
+ * and tooling can inspect what's running without an official client for it (see this file's own
+ * "No official Admin API client" header note — same "fetch the REST endpoint directly" posture
+ * as every other function here; this is simply the one REST endpoint none of them touch yet).
+ * The endpoint takes a single JSON string, no parameter binding — build `sql` with any
+ * caller-supplied values already escaped (single quotes doubled) before calling this.
+ * @param {{restateAdminURL: string, sql: string}} params
+ * @returns {Promise<Record<string, unknown>[]>}
+ */
+export async function queryRestate({ restateAdminURL, sql }) {
+	const response = await fetch(`${restateAdminURL}/query`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+		body: JSON.stringify({ query: sql }),
+	})
+	if (!response.ok) {
+		const body = await response.text().catch(() => '')
+		throw new restate.TerminalError(
+			`Restate SQL query failed: ${response.status} ${response.statusText} — ${body.slice(0, 500)}`,
+			{ errorCode: ERROR_INFRASTRUCTURE },
+		)
+	}
+	/** @type {{rows: Record<string, unknown>[]}} */
+	const { rows } = await response.json()
+	return rows
+}
+
 /**
  * Force-deletes a deployment from Restate, draining any in-flight invocations.
  * @param {string} restateAdminURL
@@ -691,6 +720,7 @@ export const sendMessageAsynSafe = async ({ restateURL, callerParams, timeout })
 
 /**
  * @typedef {Object} RestateAdmin
+ * @property {(sql: string) => Promise<Record<string, unknown>[]>} query
  * @property {() => Promise<ServiceMetadata[]>} listServices
  * @property {(params: {name: string}) => Promise<ServiceMetadata>} service
  * @property {(params: {name: string}) => Promise<HandlerMetadata[]>} listHandlers
@@ -714,6 +744,8 @@ export const sendMessageAsynSafe = async ({ restateURL, callerParams, timeout })
  */
 export function createRestateAdmin({ restateAdminURL, restateURL }) {
 	return {
+		query: (sql) => queryRestate({ restateAdminURL, sql }),
+
 		// Services
 		listServices: () => listServices({ restateAdminURL }),
 		service: ({ name }) => service({ restateAdminURL, name }),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.1.14",
+	"version": "0.1.16",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -24,8 +24,8 @@
 		"test:watch": "bun test --watch"
 	},
 	"dependencies": {
-		"@empyria/classification": "0.1.6",
-		"@empyria/common": "0.3.1",
+		"@empyria/classification": "0.1.7",
+		"@empyria/common": "0.3.2",
 		"@restatedev/pubsub": "0.3.2",
 		"@restatedev/pubsub-client": "0.3.2",
 		"@restatedev/restate-sdk": "1.17.0",

package/test/Admin.test.js

@@ -4,6 +4,7 @@ import {
 	startSubWorkflow,
 	callSubWorkflow,
 	listServices,
+	queryRestate,
 	deleteDeployment,
 	service,
 	listHandlers,
@@ -173,6 +174,27 @@ describe('listServices', () => {
 	})
 })
 
+describe('queryRestate', () => {
+	test('POSTs {query: sql} to /query and returns the rows', async () => {
+		const rows = [{ target_service_key: 'CA0001', status: 'suspended' }]
+		globalThis.fetch = mock(async (url, init) => {
+			expect(String(url)).toBe('http://admin/query')
+			expect(JSON.parse(init.body)).toEqual({ query: 'SELECT 1' })
+			return jsonResponse({ rows })
+		})
+		expect(await queryRestate({ restateAdminURL: 'http://admin', sql: 'SELECT 1' })).toEqual(
+			rows,
+		)
+	})
+
+	test('throws a TerminalError on a failed query', async () => {
+		globalThis.fetch = mock(async () => jsonResponse(null, false))
+		await expect(
+			queryRestate({ restateAdminURL: 'http://admin', sql: 'SELECT 1' }),
+		).rejects.toThrow(restate.TerminalError)
+	})
+})
+
 describe('deleteDeployment', () => {
 	test('resolves on success', async () => {
 		globalThis.fetch = mock(async () => jsonResponse({}))
@@ -486,4 +508,18 @@ describe('createRestateAdmin', () => {
 		})
 		expect(await admin.listServices()).toEqual(servicesPayload.services)
 	})
+
+	test('query() binds restateAdminURL and forwards the raw SQL', async () => {
+		const rows = [{ status: 'completed' }]
+		globalThis.fetch = mock(async (url, init) => {
+			expect(String(url)).toBe('http://admin/query')
+			expect(JSON.parse(init.body)).toEqual({ query: 'SELECT status FROM sys_invocation' })
+			return jsonResponse({ rows })
+		})
+		const admin = createRestateAdmin({
+			restateAdminURL: 'http://admin',
+			restateURL: 'http://ingress',
+		})
+		expect(await admin.query('SELECT status FROM sys_invocation')).toEqual(rows)
+	})
 })