Skip to main content

Exposed RPCs

Exposed RPCs let external clients invoke your Pikku functions via HTTP POST endpoints.

Exposing Functions​

Functions with expose: true can be called by external systems:

remote-rpc.functions.ts
loading...

Everything else is derived from the function:

  • Input validation from your types
  • Authentication from auth setting (default: true)
  • Permissions from permissions property
  • Error responses from thrown errors

See Middleware for auth configuration.

Wiring an RPC Endpoint​

Wire an HTTP endpoint that calls any exposed function:

import { wireHTTP } from '#pikku/http'
import { pikkuSessionlessFunc } from '#pikku'

// Generic RPC caller function
export const rpcCaller = pikkuSessionlessFunc<
  { name: string; data: unknown },
  unknown
>(async ({ rpc }, { name, data }) => {
  return await rpc.invokeExposed(name, data)
})

// Wire it to HTTP
wireHTTP({
  method: 'post',
  route: '/rpc/:rpcName',
  func: rpcCaller
})

External clients call it:

POST /rpc/greet
Content-Type: application/json

{
  "data": {
    "name": "Alice",
    "greeting": "Hello"
  }
}

Response:

{
  "message": "Hello, Alice!",
  "timestamp": 1234567890000,
  "serverPort": 3001
}

Type-Safe Client​

Pikku generates a type-safe client for calling external RPCs:

import { pikkuClient } from './pikku-fetch.gen.js'

const client = pikkuClient('https://api.example.com')

// Fully type-safe RPC calls
const result = await client.greet({
  name: 'Alice',
  greeting: 'Hello'
})

console.log(result.message)  // TypeScript knows the return type

The client:

  • Enforces correct input types
  • Knows exact output types
  • Handles authentication
  • Formats errors appropriately

See Fetch Client for details.

Next Steps​