feat: add playground page and embed grpcui (#35)

Author: lancevincentsalera

Dockerfile

@@ -1,5 +1,8 @@
 FROM node:19-alpine AS build
 
+ARG GRPCUI_URL=http://127.0.0.1:8081
+ENV GRPCUI_URL=$GRPCUI_URL
+
 WORKDIR /code
 
 COPY ./package.json ./package.json

Dockerfile.grpcui

@@ -0,0 +1,41 @@
+# Build grpcui from source
+FROM golang:1.24-alpine AS grpcui-build
+
+RUN apk add --no-cache git make
+
+RUN go install github.com/fullstorydev/grpcui/cmd/grpcui@aa3edefac370a32da4524893ffdca9c591ba0aeb
+
+# Final runtime image
+FROM alpine:3.21
+
+RUN apk add --no-cache ca-certificates
+
+COPY --from=grpcui-build /go/bin/grpcui /usr/local/bin/grpcui
+COPY ./public/grpcui /app/static/
+
+WORKDIR /app
+
+ENV GRPC_TARGET=localhost:50051
+ENV GRPC_PORT=8081
+ENV USE_PLAINTEXT=false
+ENV API_KEY=""
+ENV API_KEY_HEADER="dmtr-api-key"
+ENV STATIC_DIR=/app/static
+ENV CSS_FILE=/app/static/grpcui.css
+ENV JS_FILE=/app/static/grpcui.js
+
+EXPOSE 8081
+
+CMD if [ "$USE_PLAINTEXT" = "true" ]; then \
+      if [ -n "$API_KEY" ]; then \
+        grpcui -plaintext -bind 0.0.0.0 -port $GRPC_PORT -also-serve $STATIC_DIR -extra-css $CSS_FILE -extra-js $JS_FILE -rpc-header "$API_KEY_HEADER:$API_KEY" $GRPC_TARGET; \
+      else \
+        grpcui -plaintext -bind 0.0.0.0 -port $GRPC_PORT -also-serve $STATIC_DIR -extra-css $CSS_FILE -extra-js $JS_FILE $GRPC_TARGET; \
+      fi; \
+    else \
+      if [ -n "$API_KEY" ]; then \
+        grpcui -bind 0.0.0.0 -port $GRPC_PORT -also-serve $STATIC_DIR -extra-css $CSS_FILE -extra-js $JS_FILE -rpc-header "$API_KEY_HEADER:$API_KEY" $GRPC_TARGET; \
+      else \
+        grpcui -bind 0.0.0.0 -port $GRPC_PORT -also-serve $STATIC_DIR -extra-css $CSS_FILE -extra-js $JS_FILE $GRPC_TARGET; \
+      fi; \
+    fi

INFRASTRUCTURE.md

@@ -0,0 +1,190 @@
+# UTxO RPC Documentation Infrastructure
+
+This document describes the deployment architecture and infrastructure setup for the UTxO RPC documentation site.
+
+## Architecture Overview
+
+The application consists of two main services:
+
+1. **Nextra Documentation Site** - The main documentation site built with Next.js and Nextra
+2. **gRPC UI Service** - An embedded gRPC web interface for interactive API exploration
+
+## Services
+
+### Nextra Documentation (`nextra`)
+- **Port**: 8080
+- **Framework**: Next.js with Nextra theme
+- **Purpose**: Serves the main documentation website
+- **Proxy**: Routes `/grpcui/*` requests to the gRPC UI service
+
+### gRPC UI Service (`grpcui`)
+- **Port**: 8081
+- **Purpose**: Provides an interactive web UI for gRPC API exploration
+- **Integration**: Embedded as an iframe in the documentation site
+
+## Docker Configuration
+
+### Multi-Container Setup
+
+The application uses Docker Compose to orchestrate both services:
+
+```yaml
+services:
+  nextra:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        - GRPCUI_URL=http://grpcui:8081
+    ports:
+      - "8080:8080"
+    environment:
+      - PORT=8080
+
+  grpcui:
+    build:
+      context: .
+      dockerfile: Dockerfile.grpcui
+    ports:
+      - "8081:8081"
+    environment:
+      - USE_PLAINTEXT=false
+      - GRPC_TARGET=mainnet.utxorpc-v0.demeter.run:443
+      - API_KEY=utxorpc13rfqzhrntg93wh7uwg8
+      - API_KEY_HEADER=dmtr-api-key
+```
+
+### Build Arguments & Environment Variables
+
+#### Nextra Service
+- `GRPCUI_URL` (build arg): URL for proxying gRPC UI requests (configured at build time)
+- `PORT`: Port the Next.js server listens on
+
+#### gRPC UI Service
+- `USE_PLAINTEXT`: Whether to use plaintext connection (false for SSL/TLS)
+- `GRPC_TARGET`: Target gRPC server endpoint
+- `API_KEY`: Authentication key for the gRPC service
+- `API_KEY_HEADER`: Header name for the API key (default: "dmtr-api-key")
+- `GRPC_PORT`: Port for the gRPC UI service (default: 8081)
+
+## Deployment
+
+### Local Development
+
+1. **Start both services**:
+   ```bash
+   docker-compose up --build
+   ```
+
+2. **Access the application**:
+   - Documentation: http://localhost:8080
+   - gRPC UI (direct): http://localhost:8081
+   - gRPC UI (embedded): http://localhost:8080/grpcui
+
+### Production Deployment
+
+For production deployments:
+
+1. **Update environment variables** in `docker-compose.yml`:
+   ```yaml
+   environment:
+     - GRPC_TARGET=your-production-grpc-endpoint:443
+     - API_KEY=your-production-api-key
+     - API_KEY_HEADER=your-auth-header-name
+   ```
+
+2. **Configure build arguments** for internal service communication:
+   ```yaml
+   args:
+     - GRPCUI_URL=http://grpcui:8081
+   ```
+
+3. **Deploy with Docker Compose**:
+   ```bash
+   docker-compose -f docker-compose.yml up -d
+   ```
+
+## Version Pinning
+
+The infrastructure uses pinned versions for reproducibility:
+
+- **Go**: `golang:1.24-alpine`
+- **Alpine Linux**: `alpine:3.21`
+- **Node.js**: `node:19-alpine`
+- **gRPC UI**: Commit hash `aa3edefac370a32da4524893ffdca9c591ba0aeb`
+
+## Network Configuration
+
+### Internal Communication
+- Services communicate via Docker's internal networking
+- The `nextra` service proxies requests to `grpcui:8081`
+- gRPC UI binds to `0.0.0.0:8081` to accept connections from other containers
+
+### External Access
+- **Port 8080**: Main documentation site
+- **Port 8081**: Direct access to gRPC UI (optional)
+
+## Configuration Examples
+
+### Different gRPC Endpoints
+
+**Local Development (Plaintext)**:
+```yaml
+environment:
+  - USE_PLAINTEXT=true
+  - GRPC_TARGET=localhost:50051
+  - API_KEY=""
+```
+
+**Demeter Mainnet (SSL)**:
+```yaml
+environment:
+  - USE_PLAINTEXT=false
+  - GRPC_TARGET=mainnet.utxorpc-v0.demeter.run:443
+  - API_KEY=utxorpc13rfqzhrntg93wh7uwg8
+  - API_KEY_HEADER=dmtr-api-key
+```
+
+**Custom Endpoint**:
+```yaml
+environment:
+  - USE_PLAINTEXT=false
+  - GRPC_TARGET=api.example.com:443
+  - API_KEY=your-api-key
+  - API_KEY_HEADER=authorization
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Refused Errors**:
+   - Ensure gRPC UI service binds to `0.0.0.0` not `127.0.0.1`
+   - Check Docker network connectivity between services
+
+2. **Build-time vs Runtime Configuration**:
+   - `GRPCUI_URL` must be set as a build argument for Next.js rewrites
+   - gRPC connection settings can be runtime environment variables
+
+3. **SSL/TLS Issues**:
+   - Set `USE_PLAINTEXT=false` for encrypted endpoints
+   - Ensure the target endpoint supports TLS
+
+### Logs
+
+View service logs:
+```bash
+# All services
+docker-compose logs
+
+# Specific service
+docker-compose logs nextra
+docker-compose logs grpcui
+```
+
+## Security Considerations
+
+- API keys are passed as environment variables
+- Use Docker secrets for sensitive production deployments
+- The gRPC UI service only accepts connections from the documentation service
+- SSL/TLS is enforced for production gRPC endpoints

components/button.tsx

@@ -0,0 +1,34 @@
+import Link from "next/link";
+import React from "react";
+
+export function Button(props: { service: string; method: string }) {
+    return (
+        <div className="inline-flex ml-4 self-end">
+            <Link
+                href={{
+                    pathname: "/playground",
+                    query: { service: props.service, method: props.method },
+                }}
+                className="inline-flex items-center text-center gap-2 bg-[#00696D] hover:bg-[#27A0A1] active:bg-[#004C4E] transition-bg duration-150 text-white text-sm font-medium rounded-md border border-transparent focus:outline-none focus:ring-2 focus:ring-blue-600 focus:ring-offset-2 focus:ring-offset-white dark:focus:ring-offset-gray-800 py-1.5 px-2"
+            >
+
+                Try it out
+                <svg
+                    className="w-3 h-3"
+                    width="16"
+                    height="16"
+                    viewBox="0 0 16 16"
+                    fill="none"
+                >
+                    <path
+                        d="M5.27921 2L10.9257 7.64645C11.1209 7.84171 11.1209 8.15829 
+               10.9257 8.35355L5.27921 14"
+                        stroke="currentColor"
+                        strokeWidth="2"
+                        strokeLinecap="round"
+                    />
+                </svg>
+            </Link>
+        </div>
+    );
+}

components/playground_runner.tsx

@@ -0,0 +1,90 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+import { useRouter } from "next/router";
+import React from "react";
+
+type GrpcUiMessageData = {
+  type: "grpcui-ready" | "grpc-is-ready";
+};
+
+export default function PlaygroundRunner() {
+  const { query } = useRouter();
+  const [grpcUiIsReady, setGrpcUiIsReady] = useState(false);
+  const [loaded, setLoaded] = useState(false);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
+  const service = query.service as string | undefined;
+  const method = query.method as string | undefined;
+
+  // On Component Initialize
+  useEffect(() => {
+    function onMessage(e: MessageEvent<GrpcUiMessageData>) {
+      if (e.data.type === "grpcui-ready") {
+        setGrpcUiIsReady(true);
+        clearInterval(intervalId);
+      }
+    }
+    window.addEventListener("message", onMessage);
+
+    // Send a message to the iframe to check if it's ready
+    const intervalId = setInterval(() => {
+      if (grpcUiIsReady) return;
+      iframeRef.current?.contentWindow?.postMessage(
+        { type: "grpc-is-ready" } as GrpcUiMessageData,
+        window.location.origin
+      );
+    }, 100);
+
+    // Cleanup
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+
+  useEffect(() => {
+    if (!grpcUiIsReady || service == undefined || method == undefined) return;
+
+    const iframeContentWindow = iframeRef.current?.contentWindow;
+    if (!iframeContentWindow) return;
+
+    iframeContentWindow.postMessage(
+      { type: "grpc-select", service, method },
+      window.location.origin
+    );
+    // Remove the loading UI
+  }, [grpcUiIsReady, service, method]);
+
+  useEffect(() => {
+    if (grpcUiIsReady) {
+      setLoaded(true);
+    }
+  }, [grpcUiIsReady]);
+
+  return (
+    <div className="relative h-[160vh] rounded-lg overflow-hidden">
+      {!loaded && (
+        <div className="absolute inset-0 bg-white dark:bg-[#111111] pt-6">
+          <div className="flex flex-col gap-4">
+            <div className="w-[400px] h-10 animate-pulse rounded-full bg-[#1F2929]" />
+            <div className="w-[400px] h-10 animate-pulse rounded-full bg-[#1F2929]" />
+            <div className="w-full h-56 rounded-xl animate-pulse rounded-2xl bg-[#1F2929]" />
+          </div>
+          <div className="mt-4">
+            <div className="flex gap-2">
+              <div className="bg-[#1F2929] w-20 h-7 rounded-full animate-pulse" />
+              <div className="bg-[#1F2929] w-20 h-7 rounded-full animate-pulse" />
+              <div className="bg-[#1F2929] w-20 h-7 rounded-full animate-pulse" />
+              <div className="bg-[#1F2929] w-20 h-7 rounded-full animate-pulse" />
+            </div>
+            <div className="bg-[#1F2929] w-full h-[147px] rounded-2xl animate-pulse mt-2" />
+            <div className="bg-[#1F2929] w-full h-[200px] rounded-2xl animate-pulse mt-10" />
+          </div>
+        </div>
+      )}
+
+      <iframe
+        ref={iframeRef}
+        src="/grpcui/"
+        title={`gRPC Playground — ${service ?? "-"}.${method ?? "-"}`}
+        className="w-full h-full border-0"
+      />
+    </div>
+  );
+}

docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  nextra:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        - GRPCUI_URL=http://grpcui:8081
+    ports:
+      - "8080:8080"
+    environment:
+      - PORT=8080
+    container_name: utxorpc-docs
+
+  grpcui:
+    build:
+      context: .
+      dockerfile: Dockerfile.grpcui
+    ports:
+      - "8081:8081"
+    environment:
+      - USE_PLAINTEXT=false
+      - GRPC_TARGET=mainnet.utxorpc-v0.demeter.run:443
+      - GRPC_PORT=8081
+      - API_KEY=utxorpc13rfqzhrntg93wh7uwg8
+      - API_KEY_HEADER=dmtr-api-key
+    container_name: utxorpc-grpcui