@bielu/scalar-grpc 0.1.0

package/src/discovery.ts

@@ -0,0 +1,21 @@
+import { resolveDocuments as resolveDocumentsCore } from '@bielu/scalar-core'
+import type { GrpcDocumentRef } from './types'
+
+/** How the gRPC bundle discovers its AsyncAPI documents (see `resolveDocuments` in @bielu/scalar-core). */
+export const GRPC_DISCOVERY = {
+  configKey: 'grpc',
+  globalName: '__BIELU_SCALAR_GRPC__',
+} as const
+
+/**
+ * Resolves the documents to scan, in decreasing priority: an explicit override (`documents` prop);
+ * a `GrpcPluginConfig` embedded inline on the Scalar config as `config.grpc`; a
+ * `window.__BIELU_SCALAR_GRPC__` global; otherwise auto-discovery from the Scalar configuration
+ * passed as `options`.
+ */
+export function resolveDocuments(
+  options: Record<string, any> | undefined,
+  override?: GrpcDocumentRef[],
+): GrpcDocumentRef[] {
+  return resolveDocumentsCore(options, GRPC_DISCOVERY, override)
+}

package/src/grpc-bindings.ts

@@ -0,0 +1,119 @@
+import {
+  deref,
+  exampleFromSchema,
+  extractSecuritySchemes,
+  firstServerHost,
+  loadAsyncApiDocuments,
+  refName,
+  resolveServerBaseUrl,
+} from '@bielu/scalar-core'
+import type {
+  GrpcDocumentRef,
+  GrpcMessageModel,
+  GrpcMethodModel,
+  GrpcMethodTypeName,
+  GrpcServiceModel,
+} from './types'
+
+const GRPC = 'grpc'
+
+const METHOD_TYPES: ReadonlySet<string> = new Set([
+  'unary',
+  'serverStreaming',
+  'clientStreaming',
+  'bidirectionalStreaming',
+])
+
+type AnyRecord = Record<string, any>
+
+/** Resolve the message(s) an operation carries and generate an example payload for each. */
+function buildMessages(doc: AnyRecord, op: AnyRecord): GrpcMessageModel[] {
+  const refs = (Array.isArray(op.messages) ? op.messages : [])
+    .map((m: AnyRecord) => m?.$ref)
+    .filter((ref: unknown): ref is string => typeof ref === 'string')
+
+  const messages: GrpcMessageModel[] = []
+  for (const ref of refs) {
+    const message = deref(doc, { $ref: ref })
+    const name = message?.name ?? refName(ref) ?? 'message'
+    // A gRPC request is a single protobuf message; the example is one JSON object (proto3 JSON).
+    const payloadExample = exampleFromSchema(doc, message?.payload) ?? {}
+    messages.push({ name, title: message?.title, example: JSON.stringify(payloadExample, null, 2) })
+  }
+  return messages
+}
+
+function methodTypeFor(binding: AnyRecord | undefined): GrpcMethodTypeName | undefined {
+  const value = binding?.methodType
+  return typeof value === 'string' && METHOD_TYPES.has(value) ? (value as GrpcMethodTypeName) : undefined
+}
+
+/** Extract every gRPC service (channel + its operations) from a parsed AsyncAPI document. */
+export function parseGrpcServices(documentName: string, doc: AnyRecord): GrpcServiceModel[] {
+  if (!doc || typeof doc !== 'object') {
+    return []
+  }
+
+  const baseUrl = resolveServerBaseUrl(firstServerHost(doc, GRPC))
+
+  // Extract security schemes from the document so the console can read them at invoke time
+  // without re-fetching the document. Only a minimal subset is needed for auth resolution.
+  const securitySchemes = extractSecuritySchemes(doc)
+  const docSecuritySchemes = Object.keys(securitySchemes).length > 0 ? securitySchemes : undefined
+
+  const channels: AnyRecord = doc.channels ?? {}
+  const services = new Map<string, GrpcServiceModel>()
+
+  for (const channelName of Object.keys(channels)) {
+    const channel: AnyRecord = channels[channelName] ?? {}
+    const binding: AnyRecord | undefined = channel.bindings?.[GRPC]
+    if (!binding) {
+      continue
+    }
+    services.set(channelName, {
+      documentName,
+      channelName,
+      service: binding.service ?? channelName,
+      package: binding.package,
+      protoFile: binding.protoFile,
+      baseUrl,
+      methods: [],
+      securitySchemes: docSecuritySchemes,
+    })
+  }
+
+  const operations: AnyRecord = doc.operations ?? {}
+  for (const opName of Object.keys(operations)) {
+    const op: AnyRecord = operations[opName] ?? {}
+    const channelName = refName(op.channel?.$ref)
+    const service = channelName ? services.get(channelName) : undefined
+    if (!service) {
+      continue
+    }
+    const binding: AnyRecord | undefined = op.bindings?.[GRPC]
+    const model: GrpcMethodModel = {
+      id: opName,
+      method: binding?.method ?? opName,
+      methodType: methodTypeFor(binding),
+      requestType: binding?.requestType,
+      responseType: binding?.responseType,
+      idempotencyLevel: binding?.idempotencyLevel,
+      deadlineSeconds: typeof binding?.deadlineSeconds === 'number' ? binding.deadlineSeconds : undefined,
+      summary: op.summary ?? op.description,
+      messages: buildMessages(doc, op),
+    }
+    service.methods.push(model)
+  }
+
+  return [...services.values()]
+}
+
+/**
+ * Resolve the configured documents (inline object or URL) and aggregate the gRPC services they
+ * declare. Only documents that are actually AsyncAPI are considered, so OpenAPI sources in the
+ * same Scalar configuration are ignored.
+ */
+export async function loadGrpcServices(documents: GrpcDocumentRef[]): Promise<GrpcServiceModel[]> {
+  const loaded = await loadAsyncApiDocuments(documents)
+  return loaded.flatMap(({ name, doc }) => parseGrpcServices(name, doc))
+}

package/src/grpc-client.ts

@@ -0,0 +1,159 @@
+import type { DescMethod, DescService, FileRegistry, JsonValue } from '@bufbuild/protobuf'
+import { createFileRegistry, fromBinary, fromJson, toJson } from '@bufbuild/protobuf'
+import { FileDescriptorSetSchema } from '@bufbuild/protobuf/wkt'
+import { createClient } from '@connectrpc/connect'
+import { createGrpcWebTransport } from '@connectrpc/connect-web'
+
+/** The default base path `MapScalarGrpcAssets()` serves the bundle and descriptors from. */
+export const DEFAULT_ASSETS_PATH = '/bielu/scalar/grpc'
+
+// The URL this bundle was loaded from, captured at script-evaluation time (see `index.ts`). The
+// descriptor endpoint is served as a sibling of plugin.js, so this is the primary way to find it.
+let bundleScriptSrc: string | undefined
+
+/**
+ * Capture the bundle's own script URL. Must be called at module-evaluation time, while
+ * `document.currentScript` still points at the executing `<script>` tag.
+ */
+export function captureBundleScriptSrc(): void {
+  if (typeof document !== 'undefined') {
+    const src = (document.currentScript as HTMLScriptElement | null)?.src
+    if (src) {
+      bundleScriptSrc = src
+    }
+  }
+}
+
+/**
+ * The URL of the protobuf descriptor endpoint for a target base URL.
+ *
+ * When the bundle was served by `MapScalarGrpcAssets()` from the same origin as the target, the
+ * descriptors live next to plugin.js (whatever custom path it was mapped under). When the bundle
+ * came from elsewhere (e.g. a CDN in the Aspire setup), fall back to the default assets path on
+ * the target origin.
+ */
+export function descriptorsUrlFor(baseUrl: string): string {
+  const normalizedBase = baseUrl.replace(/\/+$/, '')
+  if (bundleScriptSrc && typeof window !== 'undefined') {
+    try {
+      const script = new URL(bundleScriptSrc, window.location.href)
+      const target = new URL(normalizedBase || window.location.origin, window.location.href)
+      if (script.origin === target.origin) {
+        return new URL('descriptors', script.href).href
+      }
+    } catch {
+      // Fall through to the default path on the target origin.
+    }
+  }
+  return `${normalizedBase}${DEFAULT_ASSETS_PATH}/descriptors`
+}
+
+// Cache the parsed registry per descriptor URL; failed loads are evicted so a later invoke retries.
+const registryCache = new Map<string, Promise<FileRegistry>>()
+
+async function fetchRegistry(url: string): Promise<FileRegistry> {
+  const response = await fetch(url, { headers: { accept: 'application/x-protobuf' } })
+  if (!response.ok) {
+    throw new Error(
+      `Failed to load protobuf descriptors from ${url} (HTTP ${response.status}). ` +
+        `Ensure the target app calls MapScalarGrpcAssets().`,
+    )
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer())
+  return createFileRegistry(fromBinary(FileDescriptorSetSchema, bytes))
+}
+
+/** Load (and cache) the protobuf descriptor registry served by the .NET package. */
+export function loadDescriptorRegistry(url: string): Promise<FileRegistry> {
+  let cached = registryCache.get(url)
+  if (!cached) {
+    cached = fetchRegistry(url)
+    cached.catch(() => registryCache.delete(url))
+    registryCache.set(url, cached)
+  }
+  return cached
+}
+
+/** Resolve a service and RPC method from the descriptor registry, with actionable errors. */
+export function resolveMethod(
+  registry: FileRegistry,
+  serviceName: string,
+  methodName: string,
+): { service: DescService; method: DescMethod } {
+  const service = registry.getService(serviceName)
+  if (!service) {
+    throw new Error(
+      `Service "${serviceName}" was not found in the server's descriptors — ` +
+        `is it mapped via MapGrpcService<T>()?`,
+    )
+  }
+  const method = service.methods.find((candidate) => candidate.name === methodName)
+  if (!method) {
+    throw new Error(`Method "${methodName}" was not found on service "${serviceName}".`)
+  }
+  return { service, method }
+}
+
+export type GrpcCallOptions = {
+  /** The target origin (scheme://host) the gRPC-Web calls are sent to. */
+  baseUrl: string
+  /** Call metadata — gRPC-Web metadata is plain HTTP headers. */
+  headers?: Record<string, string>
+  /** Call deadline in milliseconds. */
+  timeoutMs?: number
+}
+
+type DynamicClient = Record<string, (input: unknown, options?: unknown) => unknown>
+
+function clientFor(service: DescService, options: GrpcCallOptions): DynamicClient {
+  const transport = createGrpcWebTransport({ baseUrl: options.baseUrl })
+  // The registry-derived DescService is untyped, so the generated client surface degrades to a
+  // dynamic method map — exactly what a console driven by runtime descriptors needs.
+  return createClient(service, transport) as unknown as DynamicClient
+}
+
+/** Invoke a unary RPC with a proto3-JSON request; returns the response as proto3 JSON. */
+export async function invokeUnary(
+  registry: FileRegistry,
+  serviceName: string,
+  methodName: string,
+  requestJson: JsonValue,
+  options: GrpcCallOptions,
+): Promise<JsonValue> {
+  const { service, method } = resolveMethod(registry, serviceName, methodName)
+  const request = fromJson(method.input, requestJson, { registry })
+  const client = clientFor(service, options)
+  const response = await client[method.localName](request, {
+    headers: options.headers,
+    timeoutMs: options.timeoutMs,
+  })
+  return toJson(method.output, response as never, { registry })
+}
+
+/**
+ * Invoke a server-streaming RPC with a proto3-JSON request. Each response message is passed to
+ * `onMessage` as proto3 JSON; resolves with the total message count once the stream completes.
+ */
+export async function invokeServerStreaming(
+  registry: FileRegistry,
+  serviceName: string,
+  methodName: string,
+  requestJson: JsonValue,
+  options: GrpcCallOptions,
+  onMessage: (message: JsonValue) => void,
+): Promise<number> {
+  const { service, method } = resolveMethod(registry, serviceName, methodName)
+  const request = fromJson(method.input, requestJson, { registry })
+  const client = clientFor(service, options)
+  const stream = client[method.localName](request, {
+    headers: options.headers,
+    timeoutMs: options.timeoutMs,
+  }) as AsyncIterable<unknown>
+
+  let count = 0
+  for await (const message of stream) {
+    count += 1
+    onMessage(toJson(method.output, message as never, { registry }))
+  }
+  return count
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+import { bootstrapConsole } from '@bielu/scalar-core'
+import GrpcConsole from './components/GrpcConsole.vue'
+import { GRPC_DISCOVERY } from './discovery'
+import { captureBundleScriptSrc } from './grpc-client'
+import { GRPC_PLUGIN_SPEC } from './plugin'
+
+export { createGrpcPlugin } from './plugin'
+export { loadGrpcServices, parseGrpcServices } from './grpc-bindings'
+export { descriptorsUrlFor, loadDescriptorRegistry } from './grpc-client'
+export type {
+  GrpcDocumentRef,
+  GrpcMethodModel,
+  GrpcMethodTypeName,
+  GrpcPluginConfig,
+  GrpcServiceModel,
+} from './types'
+
+// Remember where this bundle was loaded from — the protobuf descriptor endpoint is served as a
+// sibling of plugin.js. Must run now, while `document.currentScript` is still this script tag.
+captureBundleScriptSrc()
+
+// Register the console Web Component and hook `window.Scalar.createApiReference` so every Scalar
+// API Reference on the page picks up the gRPC plugin (see @bielu/scalar-core's bootstrap).
+bootstrapConsole(
+  {
+    ...GRPC_PLUGIN_SPEC,
+    discovery: GRPC_DISCOVERY,
+    stylesId: 'bielu-grpc-styles',
+    wrappedFlag: '__bieluGrpcWrapped',
+  },
+  GrpcConsole,
+)

package/src/plugin.ts

@@ -0,0 +1,39 @@
+import { createConsolePlugin } from '@bielu/scalar-core'
+import type { GrpcDocumentRef } from './types'
+
+/** The custom element tag the console is rendered as (registered in `index.ts`). */
+export const GRPC_CONSOLE_TAG = 'bielu-grpc-console'
+
+/** The Scalar plugin's identifier, used to detect (and de-duplicate) an existing registration. */
+export const GRPC_PLUGIN_NAME = 'bielu-grpc'
+
+/** How the gRPC console registers with Scalar (plugin name, element tag, sidebar label). */
+export const GRPC_PLUGIN_SPEC = {
+  pluginName: GRPC_PLUGIN_NAME,
+  elementTag: GRPC_CONSOLE_TAG,
+  sidebarLabel: 'gRPC',
+} as const
+
+/**
+ * The structural shape of a Scalar API Reference plugin. Declared locally (a structural copy of
+ * @bielu/scalar-core's type) so the published declaration files never reference the private core
+ * package; Scalar validates it at runtime.
+ */
+export type ApiReferencePlugin = () => {
+  name: string
+  extensions: unknown[]
+  views?: Record<string, unknown[]>
+  hooks?: Record<string, unknown>
+  apiClientPlugins?: unknown[]
+}
+
+/**
+ * Creates the gRPC console plugin for the Scalar API Reference.
+ *
+ * The view's `component` is the custom element tag name (a string), so Scalar's own Vue renders a
+ * plain element — our Web Component (with its own Vue + styles) takes over from there. The AsyncAPI
+ * documents (discovered from the Scalar configuration at registration time) are passed to the
+ * element as the `documents` prop, so the console does not depend on Scalar binding its config.
+ */
+export const createGrpcPlugin = (documents?: GrpcDocumentRef[]): ApiReferencePlugin =>
+  createConsolePlugin(GRPC_PLUGIN_SPEC, documents)

package/src/types.ts

@@ -0,0 +1,88 @@
+/** The four kinds of RPC a gRPC method can be (camelCase wire tokens from the `grpc` binding). */
+export type GrpcMethodTypeName =
+  | 'unary'
+  | 'serverStreaming'
+  | 'clientStreaming'
+  | 'bidirectionalStreaming'
+
+/** A reference to an AsyncAPI document — either by URL or as an already-parsed object. */
+export type GrpcDocumentRef = {
+  /** Logical document name (matches the AsyncAPI/source title). */
+  name: string
+  /** URL the AsyncAPI JSON document is served from. */
+  url?: string
+  /** An inline, already-parsed document object (from a Scalar source's `content`). */
+  doc?: Record<string, any>
+}
+
+/** Configuration consumed by the gRPC console plugin. */
+export type GrpcPluginConfig = {
+  /**
+   * AsyncAPI documents to scan for gRPC bindings. Normally derived automatically from the
+   * Scalar configuration's `sources`; only set explicitly to override that discovery.
+   */
+  documents: GrpcDocumentRef[]
+}
+
+/** A message an RPC method can carry, with a generated example payload. */
+export type GrpcMessageModel = {
+  /** Message name/key (e.g. `helloRequest`). */
+  name: string
+  /** Human-friendly title, when the document provides one. */
+  title?: string
+  /**
+   * A ready-to-send example of the request message, as a pretty-printed JSON object string
+   * (proto3 JSON mapping), generated from the message payload schema.
+   */
+  example: string
+}
+
+/** A single RPC method discovered from an AsyncAPI operation with a `grpc` binding. */
+export type GrpcMethodModel = {
+  /** AsyncAPI operation id. */
+  id: string
+  /** The RPC method name actually used on the wire, e.g. `SayHello`. */
+  method: string
+  /** The kind of RPC. Missing method types are treated as unary. */
+  methodType?: GrpcMethodTypeName
+  /** The fully-qualified protobuf type of the request message, e.g. `greet.HelloRequest`. */
+  requestType?: string
+  /** The fully-qualified protobuf type of the response message, e.g. `greet.HelloReply`. */
+  responseType?: string
+  /** The declared idempotency level (e.g. `noSideEffects`). */
+  idempotencyLevel?: string
+  /** The call deadline in seconds, when the operation declares one. */
+  deadlineSeconds?: number
+  summary?: string
+  /** Messages this operation carries, each with an example payload to prefill the editor. */
+  messages: GrpcMessageModel[]
+}
+
+/** A minimal representation of an AsyncAPI security scheme, extracted at document-parse time. */
+export type SecuritySchemeModel = {
+  /** e.g. `'apiKey'`, `'http'`, `'oauth2'`, `'openIdConnect'`. */
+  type: string
+  /** For `apiKey`: `'query'`, `'header'`, or `'cookie'`. */
+  in?: string
+  /** For `apiKey`: the query-param or header field name. */
+  name?: string
+  /** For `http`: `'bearer'`, `'basic'`, etc. */
+  scheme?: string
+}
+
+/** A gRPC service discovered from an AsyncAPI channel with a `grpc` binding. */
+export type GrpcServiceModel = {
+  documentName: string
+  channelName: string
+  /** The fully-qualified service name, e.g. `greet.Greeter`. */
+  service: string
+  /** The protobuf package the service belongs to, e.g. `greet`. */
+  package?: string
+  /** Path or URL to the `.proto` file that defines the service. */
+  protoFile?: string
+  /** Best-effort absolute base URL (scheme://host) resolved from the AsyncAPI servers. */
+  baseUrl: string
+  methods: GrpcMethodModel[]
+  /** Security schemes declared in this service's AsyncAPI document, keyed by scheme name. */
+  securitySchemes?: Record<string, SecuritySchemeModel>
+}