PulseRPC IDL Syntax

The PulseRPC Interface Definition Language (IDL) lets you define your service contract in a language-agnostic way.

Namespaces

Every IDL file must declare a namespace:

namespace myservice

The namespace becomes the package/module name in generated code.

Comments

// Comments start with //

// Multi-line comments are supported                                                                                                                                                                                                        
// by stacking single-line comments                                                                                                                                                                                                         
// on consecutive lines

Enums

Define a set of valid values:

enum Status {
    pending
    active
    closed
}

Error Declarations

Define error codes that methods can raise:

errors {
    1001 NotFound "Not Found"
    1002 InvalidInput "Invalid Input"
    1003 PermissionDenied "Permission Denied"
}

Each error declaration has three parts:

Error Codes

Error codes can be any integer. JSON-RPC reserves certain ranges:

Using Errors in Methods

Methods can declare which errors they raise using the raises() clause:

interface UserService {
    getUser(userId string) User raises(NotFound)
    createUser(user User) UserResponse raises(InvalidInput, PermissionDenied)
}

Namespaced Errors

Errors can be imported from other files:

// common/errors.pulse
namespace common

errors {
    1001 NotFound "Not Found"
    1002 InvalidInput "Invalid Input"
}

// service.pulse
import "common/errors.pulse"

namespace myservice

interface Service {
    getValue(id string) string raises(common.NotFound)
}

Error Documentation

Errors can be documented with comments:

// Standard application errors
errors {
    // Returned when a requested resource is not found
    1001 NotFound "Not Found"

    // Returned when input validation fails
    1002 InvalidInput "Invalid Input"
}

See Error Handling for comprehensive error documentation.

Structs

Define data structures with fields:

struct User {
    userId    string
    email     string
    age       int
    active    bool
    createdAt int      [optional]
}

Field Modifiers

Struct Inheritance

Extend existing structs:

struct BaseResponse {
    status string
    message string
}

struct UserResponse extends BaseResponse {
    user User
}

Arrays

Define lists with []:

struct Cart {
    items []CartItem
}

Maps

Define key-value maps:

struct Metadata {
    tags map[string]string
}

Interfaces

Define service interfaces:

interface UserService {
    // Returns a user by ID
    getUser(userId string) User

    // Creates a new user
    createUser(user User) UserResponse

    // Lists all users (optional return)
    listUsers() []User [optional]
}

Interface Methods

Imports

Import other IDL files:

import "common.pulse"

Complete Example

namespace checkout

enum OrderStatus {
    pending
    paid
    shipped
    cancelled
}

struct Product {
    productId    string
    name         string
    price        float
    stock        int
}

interface CatalogService {
    listProducts() []Product
    getProduct(productId string) Product [optional]
}

interface OrderService {
    createOrder(request CreateOrderRequest) OrderResponse
    getOrder(orderId string) Order [optional]
}

Next Steps