DEV Community: explita

I Built an Encrypted Ngrok Alternative — The Hardest Part Wasn't the Crypto

explita — Mon, 28 Sep 2026 22:40:17 +0000

Like pretty much every developer who has ever tested a Stripe webhook, debugged OAuth callbacks, or demoed a local Next.js app to a teammate, I’ve spent years relying on tunneling tools.

And for years, the ritual looked like this:

Fire up a tunnel tool.
Get hit with an unmemorable generated URL or an account upgrade paywall.
Test your webhook.
Realize the tunnel relay in the cloud is sitting in the middle of your connection, terminating TLS, and technically has cleartext access to every authorization header, test credit card, and secret cookie crossing the wire.

Eventually, frustration turned into curiosity: What would it take to build a modern, high-throughput reverse tunnel that treats the relay server as untrusted by default?

Not just a generic port forwarder, but something that gives you:

Inner session encryption (AES-256-GCM) so the relay server cannot read your payloads.
Flawless streaming & WebSocket support (Next.js Turbopack HMR, Vite, Server-Sent Events).
A zero-dependency local inspector & instant replay (press r in the terminal to replay the last webhook without re-triggering it from Stripe).
Built-in IP/CIDR firewalls right at the edge.

Here is the story of building Explita Tunnel (eta), the architecture under the hood, and the hair-pulling edge cases I hit along the way.

Where Does This Fit? (Ngrok, Cloudflare, Tailscale)

Before getting into the crypto and networking guts, it’s worth addressing the elephant in the room: why not just use an existing tool?

Ngrok: Still the gold standard for developer ergonomics, but recent years brought pricing changes, random URLs on free tiers, browser interstitial warning pages, and closed-source relays that terminate TLS in cleartext.
Cloudflare Tunnel (cloudflared): Incredible for production services running on your own domain, but it requires routing your domain through Cloudflare DNS, configuring credentials, and managing daemon configs. It’s heavy when all you want is a 5-second throwaway URL to test a webhook.
Tailscale Funnel: Superb if your nodes already live on a Tailnet, but it requires Tailscale client routing and isn’t geared as a friction-free public webhook ingress for 3rd parties like Stripe or GitHub.

Tool	Setup Friction	Relay Trust Model	Best For
Ngrok	Minimal (CLI binary)	Cleartext relay (TLS terminated at edge)	Rapid prototyping & client demos
Cloudflare Tunnel	High (Domain on Cloudflare DNS + config)	Cleartext relay (TLS terminated at edge)	Persistent production services on custom domains
Tailscale Funnel	Moderate (Tailnet device auth)	Cleartext relay (Tailnet ingress node)	Private internal team mesh & node access
Explita Tunnel	Minimal (CLI binary, zero config)	Untrusted relay (Inner AES-256-GCM session)	Webhook testing, HMR dev, & privacy-conscious local work

To be clear about trade-offs: if you're deploying a high-availability production service running 24/7 on a permanent company domain, tools like Cloudflare Tunnel or an AWS ALB are still the standard choice. Explita Tunnel is purpose-engineered for the active development loop: instantaneous throwaway ingress, local webhook testing, HMR stability, and inner payload confidentiality without account friction.

I wanted something with the 2-second speed of Ngrok, but with zero configuration, automatic subdomains, and an architecture where the relay server is treated as an untrusted pipe.

The Trust Problem with Traditional Tunnels

Most tunneling setups work like standard reverse proxies:

[Browser / Webhook] ---> (HTTPS/TLS) ---> [Tunnel Cloud Server] ---> (WebSocket/TCP) ---> [Your CLI Agent] ---> [Localhost:3000]

Notice what happens at the Tunnel Cloud Server: TLS terminates there.

If the tunnel server is compromised, or if you're using a shared multi-tenant cluster, whoever operates that gateway has full visibility into your raw plaintext HTTP headers, authorization bearer tokens, customer webhook payloads, and environment secrets.

To fix this, I implemented an Untrusted Relay Architecture.

1. Untrusted Relay Architecture (ECDH + AES-256-GCM)

I designed the wire protocol so that even if an attacker completely controls the tunnel server, they see nothing but encrypted noise.

Here’s how the handshake works:

When your CLI (eta 3000) establishes its control WebSocket with the server, it sends a hello packet containing an ephemeral ECDH public key (using the NIST P-256 / prime256v1 curve).
The server responds with its own ephemeral public key inside a ready frame.
Both sides perform Elliptic Curve Diffie-Hellman to compute a shared secret, and derive a 256-bit symmetric key using HKDF-SHA256.
Every subsequent frame—incoming HTTP requests, response chunks, headers, and WebSocket data—is enveloped into an authenticated AES-256-GCM ciphertext:

{
  "type": "encrypted",
  "iv": "0H/rhkojjBR1sEgL",
  "tag": "2DAsewK7mcu2/EWxbs...",
  "data": "lZczO9B..."
}

Here’s the actual Node.js crypto derivation under the hood:

import { createECDH, hkdfSync } from "node:crypto";

export function generateEcdhKeyPair() {
  const ecdh = createECDH("prime256v1");
  ecdh.generateKeys();
  const publicKey = ecdh.getPublicKey("base64");

  return {
    publicKey,
    computeSharedKey: (peerPublicKey: string): Buffer => {
      const rawSecret = ecdh.computeSecret(peerPublicKey, "base64");
      // Derive a 256-bit (32-byte) symmetric key via HKDF
      const derived = hkdfSync(
        "sha256",
        rawSecret,
        "",
        "explita-tunnel-e2ee",
        32,
      );
      return Buffer.from(derived);
    },
  };
}

Session Fingerprints & Verifying the Handshake

To confirm that the key exchange succeeded and give each connection a unique cryptographic identity, the agent computes and displays a truncated SHA-256 session fingerprint:

✓ Key exchange complete • ECDH P-256 + AES-GCM (256-bit)
Fingerprint: SHA256:2c:2a:07:7b:a7:c4:7d:71:a1:fc:5a:99:85:69:18:67

This fingerprint deterministically binds the client's public key, the server's public key, and the derived session key. It gives you immediate visual confirmation that the tunnel is running with inner encryption active rather than in plaintext. Whenever your connection reconnects or rotates, a fresh keypair is negotiated and the fingerprint changes.

(Looking ahead: because ephemeral ECDH alone does not authenticate the server's identity, I plan to add server-identity key signing in a future release so the agent can cryptographically verify the gateway out-of-the-box).

And what about performance? On modern hardware with AES-NI instructions, AES-256-GCM throughput impact is negligible (<1-2% CPU). The --no-encrypt flag remains available for low-power embedded microcontrollers or local testing when you want to eliminate cryptographic compute completely.

What Happens on Reconnect & Key Rotation?

If your laptop sleeps or your Wi-Fi drops, the client enters an exponential backoff reconnect loop. The server reserves your subdomain with a 60-second grace lock so nobody snatches it while you're offline.

Upon reconnecting, the agent and server negotiate a brand-new ephemeral ECDH keypair, rotating the session key automatically. In-flight requests during the drop fail cleanly, and subsequent traffic immediately resumes over the fresh cipher.

2. The Nightmare of Streaming & WebSockets (Gotchas from the Trenches)

Building basic request-response forwarding is easy. Anyone can write a 50-line Node.js prototype that fetches a URL and sends it over a socket.

What's hard is real-world web traffic.

The Next.js / Vite HMR Problem

When you run a modern frontend framework through a tunnel, it opens a persistent WebSocket connection for Hot Module Replacement (e.g. /_next/hmr).

During early testing with Next.js 15 + Turbopack, my browser console kept spamming:

[HMR] connected
[HMR] disconnected
[HMR] connected
...

Tracking this down took hours of packet tracing. It boiled down to two subtle bugs:

Lost this in Fastify's WebSocket Handler:
Fastify’s @fastify/websocket calls route handlers with wsHandler.call(this, socket, request) where this is bound to the Fastify instance instead of my router class. A standard class method routeWs(socket, req) lost its scope, crashed on a property lookup, and triggered an abnormal closure (1006), kicking off an endless reconnect loop in the browser. Changing it to an arrow property (routeWs = (socket, req) =>) pinned the class context and fixed it instantly.
Server-Sent Events (SSE) vs Compression:
When you enable Brotli/Gzip compression on your edge proxy with @fastify/compress, it loves to buffer text streams until it hits a threshold (usually 1KB). But Server-Sent Events (text/event-stream) require immediate flushes. If your compression middleware buffers chunks, your live stream hangs. I tuned the compression regex to explicitly bypass SSE streams:

   // Compress text and JSON, but exclude streaming event-streams
   customTypes: /^text\/(?!event-stream)|\+json$|\+xml$/;

Once those were solved, full-duplex WebSockets and HMR ran buttery smooth with zero drops.

3. Developer Experience: Instant Replay & Live Wire

Most CLI tools either show you nothing (just a static URL) or dump an overwhelming firehose of debug logs into your terminal.

I wanted a better middle ground:

1-Key Request Replay (`r`)

Ever spent 10 minutes setting up a checkout in Stripe Test Mode just to trigger a single webhook event to your local app?

When your local code throws a 500 error because of a typo, you normally have to go back to Stripe and trigger the event again.

With Explita Tunnel, you don't. Just hit r in your terminal.

⚡ Replaying: POST /api/webhooks/stripe...
200 OK POST /api/webhooks/stripe 14ms

The agent stores recent requests in an in-memory ring buffer and replays the exact headers and payload directly against your local port without making round-trips to the internet.

Security note on replay: Because webhooks carry sensitive authentication tokens (like Stripe-Signature), the ring buffer is stored strictly in volatile RAM (never written to disk), capped at 50 requests (with a 2MB payload ceiling), and wiped from memory the moment the process terminates.

Live Wire Inspector (`w`)

Instead of flooding the console with raw frames by default, the terminal stays clean. But whenever you want to see what's happening on the wire, just tap w to toggle the live wire inspector:

[WIRE <-] 🔒 CIPHERTEXT {"type":"encrypted","iv":"...","tag":"...","data":"..."}
[WIRE ->] 🔒 CIPHERTEXT {"type":"encrypted","iv":"...","tag":"...","data":"..."}

Tap w again, and you're back to the clean request stream.

Pro-tip I learned: When implementing a wire inspector, filter out internal keepalive ping and pong frames! Heartbeats tick every 15 seconds; nothing ruins a debug session faster than keepalive noise drowning out the API payload you were trying to read.

Built-in Local Web Dashboard

If you prefer a browser UI, the agent spins up a local inspector on http://127.0.0.1:39755 with live SSE updates, payload formatting, header inspection, and image previews. No external SaaS dashboard required.

4. Edge Security: IP & CIDR Firewalls

When you expose a local server to the internet, it’s exposed to everyone. Bots and port scanners will find it within minutes.

Instead of writing custom middleware in your local development server, you can tell the tunnel agent to enforce an IP allowlist right at the gateway:

eta 3000 --allow-ip "102.89.42.10, 192.168.1.0/24"

Any unauthorized caller is rejected at the edge with an HTTP 403 Forbidden before the request ever touches your machine.

5. Trying It Out

Explita Tunnel (eta) is currently in early release.

You can install the CLI globally:

npm install -g @explita/cli
# or with pnpm
pnpm add -g @explita/cli

Expose your local app:

# Expose port 3000
eta 3000

# Expose with a custom subdomain, auth, and IP restriction
eta 3000 -s myapp -a "dev:secret" -i "1.2.3.4"

You can learn more and get access at:

👉 Website & Documentation: https://tunnel.explita.ng

What I Learned

Building networking tools from scratch is humbling. You think the hard part is cryptography or concurrency, but in reality, the hardest parts are the edge cases:

Socket close codes (1000 vs 1006 vs 1008)
Chunk encoding across binary and utf-8 streams
Keeping terminal interfaces responsive in raw TTY mode
Ensuring your relay never buffers what should be streaming

If you’re building developer tools or experimenting with WebSockets and cryptography in Node.js, I hope this breakdown gives you some useful ideas for your own architecture. And if you have any questions or feedback, let's chat in the comments!

Generate Zod schemas & guard your DB automatically.

explita — Fri, 22 May 2026 08:08:21 +0000

If you use Prisma, you already know it's a fantastic ORM with excellent developer experience. But there's a common friction point almost all of us hit when building real-world APIs: input validation and sanitization.

Prisma is strict. If a user passes an unknown field in a .create() or .update() payload (like an injected isAdmin: true), Prisma throws an error. So what do you do? You end up writing tedious mapping functions, picking fields manually, or writing massive Zod schemas by hand to validate and strip out the junk before it reaches Prisma.

What if your Prisma schema could just... do it all for you?

Enter Prisma Guard 🛡️.

What is Prisma Guard?

Prisma Guard is the ultimate Prisma companion designed to bridge the gap between database models and API validation. It does two main things:

Runtime Protection (The Guard): A Prisma Client extension that silently strips unknown fields from your queries at runtime.
Schema Generation (The Magic): Automatically transforms your .prisma models into robust, decorated Zod schemas with complete type-safety.

It's completely zero-config out of the box (it even manages your .gitignore and Prettier formatting for generated files), but offers immense power for those who need custom validation logic.

✌️ Two Ways to Use It

Depending on your needs, you can use Prisma Guard in two modes.

Mode 1: Runtime Protection Only (The Quick Fix)

If you just want to stop Prisma from throwing errors when random fields are passed from the frontend, just add the extension to your client:

import { PrismaClient } from "@prisma/client";
import { prismaGuard } from "@explita/prisma-guard";

const prisma = new PrismaClient().$extends(prismaGuard());

// Any extra fields passed to 'data' will be silently stripped
await prisma.user.create({
  data: {
    email: "user@example.com",
    poisonField: "will be removed", // Poof! Gone.
  },
});

Mode 2: Full Validation & Schema Generation (Recommended)

This is where the real magic happens. By running npx prisma-guard, it reads your Prisma schema and generates perfect Zod schemas.

Your Prisma Schema:

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  password  String
  createdAt DateTime @default(now())
}

What you get:

export const UserCreateSchema = z.object({
  email: z.string().trim().min(1, { message: "This field is required" }),
  password: z.string().trim().min(1),
  // id and createdAt are managed by Prisma defaults or omitted entirely depending on your config!
});

💎 Advanced Type Ergonomics & Dual Schemas

One of the biggest headaches with schema generation is that a "public" API schema shouldn't include sensitive internal database fields (like secretApiKey or tenantId).

Prisma Guard handles this beautifully by generating Dual Schemas for every model:

Public Schemas (UserCreateSchema): Respects your omission rules. Perfect for API request validation.
Scalar Schemas (UserCreateScalarSchema): Includes every database field. Perfect for internal services and database operations.

It also exports a suite of ergonomic TypeScript types (UserCreate, UserUpdate, UserCreateRequired) so your service layers are always perfectly typed.

🎨 The Power of Decorators (and the `v` proxy)

Sometimes z.string() isn't enough. You need .email(), .min(8), or custom refinement logic. Prisma Guard lets you define this cleanly using triple-slash comments (///).

Instead of polluting your Prisma schema with massive strings of Zod code, Prisma Guard introduces the v proxy in a prisma-guard.config.js file:

// prisma-guard.config.js
import { defineConfig, v } from "@explita/prisma-guard";

export default defineConfig({
  decorators: {
    // Chain validations onto the inferred Prisma type
    email: v.chain.email().trim().toLowerCase(),

    // Completely override a type
    strongPassword: v.string().min(12).regex(/[A-Z]/),
  },
});

Then, you just use them in your Prisma schema!

model User {
  id       String @id

  /// @zod.use(email)
  email    String

  /// @zod.use(strongPassword)
  password String
}

IDE Superpowers 🪄

No one likes typing out decorators from memory. Prisma Guard includes an incredible npx prisma-guard metadata --vscode command that automatically installs VS Code snippets for every Zod method. You literally get autocompletion inside your .prisma files!

⚡ Blazing Fast Performance

You might be thinking: "Doesn't a runtime guard slow down my queries?"

The answer is no. The runtime guard is designed for ultra-low latency. It uses strict $O(n)$ complexity (looping only over predefined schema fields instead of arbitrary user input), memoized whitelists, and hot-path early exits.

In benchmarks of 100,000 recursive sanitization iterations on a complex payload:

Total duration: 221.26ms
Average per query: 2.21 microseconds (0.0022ms)

If your database query takes 10-50ms, adding 0.0022ms introduces virtually 0% overhead.

🚀 Get Started in 2 Minutes

Stop wasting time manually maintaining Zod schemas that drift out of sync with your database.

Install the package:

npm install @explita/prisma-guard

Initialize your config:

npx prisma-guard init

Generate the magic:

npx prisma-guard

Check out the full documentation, advanced relation handling, and custom schema generation features on our GitHub Repository.

If Prisma Guard saves you time, I'd deeply appreciate a ⭐ on GitHub! Let me know what you think in the comments below. Happy coding! 🚀

Automatic Audit Logging in Prisma

explita — Thu, 21 May 2026 12:25:08 +0000

Picture this: A critical database record is modified or deleted in production. Customer support is flooded, and your manager asks, "Who did this, what was changed, and what did it look like before?"

If you don't have audit logging set up, you're stuck digging through database transaction logs, parsing raw server outputs, or doing forensic database recovery. It's stressful, slow, and completely avoidable.

But building audit logging is notoriously tedious:

Database Triggers are hard to maintain, slow, and don't know anything about your application context (like the HTTP Request IP or the active User Session).
Manual Service Logging requires you to write boilerplate code around every database update, mutation, and delete in your entire codebase. One missing line, and your audit log is incomplete.

To solve this once and for all, I built Prisma Audit Log.

It’s a native Prisma Client extension that automatically intercepts your queries (create, update, delete, upsert, and batch operations) to log changes. Because it runs directly inside your application code, it captures full request context and user details seamlessly.

Here is how to set it up and what it gives you.

1. The Audit Log Schema

First, add an AuditLog model to your schema.prisma file. This is where your audit records will be stored:

model AuditLog {
  id            String   @id @default(cuid())
  userId        String?  @map("user_id")
  recordId      String   @map("record_id")
  action        String   // "create" | "update" | "delete"
  model         String   // E.g. "User", "Post"
  oldData       Json?    @map("old_data")
  newData       Json?    @map("new_data")
  changedFields String[] @map("changed_fields")
  ipAddress     String?  @map("ip_address")
  userAgent     String?  @map("user_agent")
  metadata      Json?
  createdAt     DateTime @default(now()) @map("created_at")

  @@map("audit_logs")
}

2. Basic Extension Setup

You can register the audit log extension on your existing PrismaClient in seconds:

import { PrismaClient } from "@prisma/client";
import { auditLogExtension } from "@explita/prisma-audit-log";
import { getAuthContext } from "@/lib/auth"; // Your auth/request storage

const prisma = new PrismaClient().$extends(
  auditLogExtension({
    // 1. Context-Aware Logging: Automatically capture user/network context
    getContext: () => {
      const session = getAuthContext();
      return {
        userId: session?.userId || "anonymous",
        ipAddress: session?.ip,
        userAgent: session?.userAgent,
        metadata: {
          tenantId: session?.tenantId,
        },
      };
    },

    // 2. Data Sanitization: Mask passwords or security tokens globally
    maskFields: ["password", "token", "creditCard"],
    maskValue: "[REDACTED]",

    // 3. Fine-grained filtering per model
    fieldFilters: {
      User: {
        exclude: ["refreshToken", "passwordSalt"],
      },
      Payment: {
        include: ["id", "amount", "status", "createdAt"], // Whitelist only
      },
    },

    // 4. Skip unnecessary logging (e.g. high-frequency sessions)
    skip: ({ model, operation }) => {
      if (model === "Session" && operation === "create") return true;
      return false;
    },
  })
);

3. What Happens Under the Hood?

Once registered, you write your normal database queries, and Prisma Audit Log handles the rest behind the scenes.

For example, when you perform a normal Prisma update:

await prisma.user.update({
  where: { id: "user_abc" },
  data: {
    email: "newemail@example.com",
    role: "ADMIN",
  },
});

The extension intercepts this, calculates the diff between the database state before and after, and creates a record that looks like this:

{
  "id": "log_12345",
  "userId": "admin_user_id",
  "recordId": "user_abc",
  "action": "update",
  "model": "User",
  "oldData": {
    "id": "user_abc",
    "email": "oldemail@example.com",
    "role": "USER"
  },
  "newData": {
    "id": "user_abc",
    "email": "newemail@example.com",
    "role": "ADMIN"
  },
  "changedFields": ["email", "role"],
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "metadata": { "tenantId": "tenant_1" },
  "createdAt": "2026-05-21T13:15:34Z"
}

4. Key Developer-First Features

Here are some details I built in to keep database logs clean, performant, and safe:

🔇 Noise-Free Update Logs

Have you ever seen audit logs filled with thousands of rows where nothing actually changed? Prisma updates often touch a model's updatedAt field or re-save unmodified fields. Prisma Audit Log automatically detects if only the timestamp fields changed, and quietly skips creating an audit entry. Your logs stay clean and noise-free.

⚡ Efficient Batch Processing

When you run bulk operations like createMany, updateMany, or deleteMany, inserting audit logs one-by-one is a performance killer. The extension groups and batches these operations, falling back gracefully to single inserts only when necessary.

🔌 Send Logs Anywhere

By default, the extension saves audit logs directly to your AuditLog table using the Prisma schema above. But if you want to stream logs to an external service (like Datadog, Axiom, or a Kafka queue), you can override the target using a custom logger callback:

auditLogExtension({
  logger: async (logs) => {
    // Send logs to Elasticsearch, Datadog, or cloud storage
    await datadogClient.send(logs);
  }
})

Give it a try! 🚀

Prisma Audit Log is open-source (MIT licensed) and ready for use. If you're building systems that require database compliance, transparency, or debugging reassurance, give it a spin:

NPM: npm i @explita/prisma-audit-log
GitHub: github.com/explita/prisma-audit-log

If this helps you sleep a bit better at night knowing your database history is safe, I'd love a GitHub ⭐! Let me know in the comments if you have any questions or feature suggestions.

Why I Built My Own TypeScript RPC Framework (And Why You Might Actually Want It)

explita — Thu, 21 May 2026 12:11:49 +0000

I have a problem.

Every time I start building a Next.js application, I find myself fighting the exact same set of friction points:

Fragile Type Safety: Type safety that works beautifully on the server but quietly disintegrates or requires manual alignment across the network boundary.
Dev-Loop Bloat: Codegen tools and compilation steps that add 15 to 30 seconds of waiting time to my dev loop.
Imprecise Error Handling: Catching errors that is either overly verbose (try-catch blocks wrapping every handler) or non-existent.
Manual Plumbing: Wiring up Redis caching, rate limiting, and circuit breakers manually, procedure by procedure, project by project.

So, I did the classic, slightly unhealthy developer thing: I built my own solution.

It’s called Actyx RPC. And before you roll your eyes at the mention of another "typesafe RPC framework" (trust me, I know there are like seventeen of these now) — hear me out. Actyx isn't just about sharing types; it's about solving the practical, everyday headaches of production backend development in TypeScript.

Here is how it works and why it’s become my go-to stack.

1. The Foundation: A Composable Base Procedure

Instead of setting up boilerplate for every route, Actyx uses a builder pattern. You define a base procedure instance that handles authentication, error mapping, telemetry, and input enrichment globally. Every procedure you create from this base builder automatically inherits these behaviors.

import { createProcedure, RedisCache } from "@explita/actyx-rpc";
import { redirect } from "next/navigation";

// Optional: Spin up Redis for cross-serverless caching and rate limiting
// const redisClient = new Redis("redis://localhost:6379");

export const procedure = createProcedure({
  // cache: new RedisCache({ redis: redisClient, defaultTTL: "5m" }),

  // 1. Establish the request context (Auth, session, user roles)
  async createContext() {
    const session = await getSession();

    if (!session) {
      return { ok: false, reason: "INVALID_SESSION" };
    }

    return {
      ok: true,
      ctx: {
        userId: session.user.id,
        role: session.user.role,
      },
    };
  },

  // 2. Automatically handle context failures (like redirects or custom errors)
  // This is only called when the createContext returns an object with ok:false
  onContextError: async ({ reason }) => {
    const loginPath = "/login";
    if (reason === "INVALID_SESSION") {
      return {
        _redirect: () => redirect(loginPath),
      };
    }
    return {
      success: false,
      reason: "UNAUTHORIZED",
      message: "Unauthorized access",
    };
  },

  // 3. Centralized error mapping — no try/catch pyramids in your handlers!
  onError({ error, ctx }) {
    console.error(`[Error in ${ctx.handlerName}]:`, error);

    // Map database constraints (like Prisma unique key violations) globally
    if (error.code === "P2002") {
      return {
        message: "This record already exists",
        reason: "CONFLICT",
        statusCode: 409,
      };
    }
  },

  // 4. Enrich every incoming handler input with context variables automatically
  enrichInput(ctx) {
    return { userId: ctx.userId };
  },
});

Now, every procedure created from this procedure builder gets auth context checks, global error transforms, and user ID injection with zero additional lines of code.

2. Defining and Calling Procedures

Actyx RPC keeps procedures simple. You define inputs using your validator of choice (Zod, Valibot, ArkType, Joi, Yup, or custom resolvers) and resolve them as either .query() (for reads) or .mutation() (for writes).

import { z } from "zod";
import { zodResolver } from "@explita/actyx-rpc/resolvers/zod";
import { db } from "@/lib/db";
import { procedure } from "./base-procedure";

// Create a mutation procedure
export const createPost = procedure
  .name("createPost")
  .input(
    zodResolver(
      z.object({
        title: z.string().min(1),
        body: z.string().min(10),
      }),
    ),
  )
  .mutation(async ({ ctx, input }) => {
    // ctx.userId is fully typed and available
    // input.title and input.body are validated, typed, and sanitized
    // input.userId is injected from enrichInput!
    return await db.post.create({
      data: {
        title: input.title,
        body: input.body,
        authorId: input.userId,
      },
    });
  });

When you call this procedure, Actyx returns a Go-style [data, error] tuple. No try/catch blocks needed:

const [post, err] = await createPost({
  title: "A Brand New Post",
  body: "This is a body longer than ten characters.",
});

if (err) {
  toast.error(err.message);
  return;
}

console.log(post.id); // 'post' is fully typed!

3. The Features That Surprised Me (DX Wins)

While building Actyx, I added a few features to solve my own development fatigue, and they turned out to be absolute game-changers:

💡 The `.mock()` Method (For Parallel Development)

Seeding and maintaining local databases just to test a frontend feature is exhausting. Actyx introduces first-class mocking directly in the builder chain:

export const getUser = procedure
  .name("getUser")
  .mock(() => ({
    id: "user_mock_123",
    name: "Jane Doe (Mocked)",
    email: "jane@example.com",
  }))
  .query(async ({ input }) => {
    // This expensive DB query is skipped when MOCKing is active!
    return await db.users.findUnique({ where: { id: input.id } });
  });

Set ACTYX_MOCK="true" in your environment variables, and the backend handlers are bypassed. The middleware, session validation, and inputs are still processed, but your database is never touched. Frontend devs can code against a "perfect" mock state while the backend is still being designed.

🧠 Caching with a Brain (SWR Built-in)

Actyx comes with Stale-While-revalidate (SWR) caching out of the box. You don't need Redis to get started; an in-memory cache adapter works by default, but you can plug in Redis as you scale:

export const getPost = procedure
  .cache({
    ttl: "5m", // Fresh for 5 minutes
    staleTime: "1m", // Becomes stale after 1 minute
    staleWhileRevalidate: true, // Serve stale data, refresh in the background
    key: ({ input }) => `post:${input.id}`,
  })
  .query(async ({ input }) => {
    return await db.post.findUnique({ where: { id: input.id } });
  });

🛡️ Serverless-Friendly Rate Limiting

Because Actyx can plug directly into your Redis cache adapter, rate limiting persists across serverless function invocations (like Vercel Serverless/AWS Lambda instances).

export const sendMessage = procedure
  .rateLimit({
    limit: 10,
    window: "1m",
    key: (ctx) => ctx.userId, // Limit requests per user
    message: "You're sending messages too fast!",
  })
  .mutation(async ({ input }) => {
    return await messageService.send(input);
  });

🔗 Inter-Procedure Calling (Zero Network Hops)

When procedures call other procedures, network overhead and duplicated auth logic usually slow things down. Actyx uses AsyncLocalStorage under the hood. When one procedure calls another, it bypasses context re-creation and authentication entirely while keeping the context secure:

const getAuditLog = procedure.query(async ({ ctx }) => {
  return await db.logs.findMany({ where: { userId: ctx.userId } });
});

export const getUserDashboard = procedure.query(async ({ ctx }) => {
  const user = await db.users.findUnique({ where: { id: ctx.userId } });

  // This nested call automatically inherits the parent's auth context!
  const [logs] = await getAuditLog();

  return { user, logs };
});

4. What Else is in the Box?

To make Actyx a production-ready choice, I added several advanced features:

OpenTelemetry: Native instrumentation so you can trace why a specific procedure is running slow at 3 AM.
Automatic OpenAPI Specs: Auto-generate standard OpenAPI JSON files to keep documentation from rotting.
Circuit Breakers: Prevent cascading failures when third-party microservices go down.
Adaptive Compression: Native support for gzip, deflate, and brotli.
Timeouts: Safe defaults to prevent hanging server processes.
React Hooks: Built-in hooks (useQuery, useMutation, useInfiniteQuery) for frontend state synchronization.

What I Haven't Figured Out Yet

Actyx is working great for my production projects, but it’s still in active development. Here’s what’s currently on my drawing board:

Bidirectional WebSockets: SSE (Server-Sent Events) streaming works perfectly for one-way flows (like LLM stream responses), but full bidirectional WS subscriptions are still being refined.
Performance Benchmarks: It feels lightning-fast under typical workloads, but I want to perform strict load/torture tests to publish concrete numbers.

If you have experience building scalable RPC networks or websocket adapters, I'd love to hear how you approached those challenges!

Give it a Spin 🚀

Actyx RPC is entirely open-source (MIT licensed). Break it, inspect it, and tell me what you think.

NPM: npm i @explita/actyx-rpc
GitHub: github.com/explita/actyx-rpc

P.S. — The name "Actyx" comes from "action" + "tyx" (as in type safety). Naming is hard. If you have a better suggestion, I'm all ears!