De Zod a Protobuf: contratos de tipo fuerte entre Laravel y Next.js usando gRPC-Web sobre Cloudflare Workers
Introducción: El problema de los contratos débiles
Cuando trabajamos con arquitecturas separadas entre frontend y backend, el tipo de dato que enviamos y recibimos se convierte en una fuente constante de errores. En el ecosistema JavaScript/TypeScript, Zod se ha vuelto popular para validar esquemas en tiempo de ejecución. Es útil, pero tiene un límite fundamental: es una validación reactiva. Descubre el problema cuando ya es tarde, cuando los datos llegaron malformados a producción.
La pregunta que nos hicimos fue simple: ¿podemos reemplazar validaciones reactivas por contratos de tipo fuerte que se respeten desde el byte cero? La respuesta fue migrar de Zod hacia Protocol Buffers (Protobuf) con gRPC-Web, ejecutando el proxy sobre Cloudflare Workers. Este artículo documenta esa arquitectura concreta entre un backend Laravel y un frontend Next.js.
Por qué Zod no alcanza para sistemas distribuidos
Zod resuelve la validación de forma elegante. Un esquema típico se ve así:
import { z } from 'zod'
const UserSchema = z.object({
id: z.number(),
email: z.string().email(),
age: z.number().min(0).max(150)
})
// Validación reactiva en runtime
const result = UserSchema.safeParse(datosExternos)
El problema aparece en tres dimensiones:
- Duplicación implícita: El backend Laravel valida con sus reglas, el frontend con Zod. Nunca están perfectamente sincronizados.
- Errores tardíos: La validación ocurre después de que el dato ya viajó por la red. Perdimos ancho de banda y latencia para descubrir un email malformado.
- Sin garantía binaria: Sobre la red viaja JSON, que es ineficiente y permisivo. Un campo numérico puede llegar como string sin que TypeScript lo intercepte hasta el parseo.
Protobuf resuelve esto mediante: contratos declarativos compartidos, serialización binaria compacta, y tipos inmutables generados en múltiples lenguajes desde una única fuente de verdad.
Arquitectura: gRPC-Web sobre Cloudflare Workers
gRPC-Web tiene una limitación conocida: los navegadores no soportan HTTP/2 de forma suficiente para gRPC nativo. Necesitamos un proxy que traduzca gRPC-Web a gRPC estándar. Tradicionalmente se usa Envoy, pero es infraestructura pesada.
Cloudflare Workers ofrece una alternativa ligera: un proxy TypeScript que corre en edge, transforma los mensajes gRPC-Web y los reenvía vía HTTP/2 al backend Laravel usando la extensión gRPC de PHP.
La arquitectura resultante:
- Next.js (frontend): Cliente gRPC-Web generado desde los protos, tipado estricto.
- Cloudflare Worker (edge): Proxy de traducción gRPC-Web ↔ gRPC con streaming soportado.
- Laravel (backend): Servidor gRPC servido via
spiral/roadrunner-grpco extensión nativa. - Protobuf (contrato): Fuente única de verdad en
.protocompartidos entre los tres sistemas.
Definiendo el contrato: los archivos .proto
Empezamos por el contrato. Este archivo vive en un repositorio compartido, submódulo de ambos proyectos:
// proto/ecommerce/v1/user.proto
syntax = "proto3";
package ecommerce.v1;
option php_namespace = "App\\Grpc\\Generated";
option php_metadata_namespace = "App\\Grpc\\Generated\\Metadata";
message User {
int64 id = 1;
string email = 2;
uint32 age = 3;
repeated string roles = 4;
Address billing_address = 5;
}
message Address {
string street = 1;
string city = 2;
string postal_code = 3;
}
message GetUserRequest {
int64 user_id = 1;
}
message GetUserResponse {
User user = 1;
}
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse);
rpc ListUsers(ListUsersRequest) returns (stream ListUsersResponse);
}
Notá dos decisiones intencionales. Primero, los tipos numéricos son explícitos: uint32 para edad que no puede ser negativa, int64 para IDs que exceden el rango de JavaScript (usaremos bigint en el cliente). Segundo, el servicio ListUsers usa stream, que nuestro proxy en Workers soportará vía la variante de streaming gRPC-Web.
Generando código: PHP para Laravel, TypeScript para Next.js
Del mismo contrato generamos ambos lados. Con el compilador protoc y el plugin de PHP:
# Generación para Laravel
protoc \
--php_out=./laravel/app/Grpc/Generated \
--grpc_out=./laravel/app/Grpc/Generated \
--plugin=protoc-gen-grpc=/usr/local/bin/grpc_php_plugin \
-I ./proto \
./proto/ecommerce/v1/user.proto
Para Next.js usamos ts-protoc-gen con el plugin de gRPC-Web:
# Generación para Next.js
protoc \
--js_out=import_style=commonjs:./nextjs/src/grpc/generated \
--grpc-web_out=import_style=typescript,mode=grpcwebtext:./nextjs/src/grpc/generated \
-I ./proto \
./proto/ecommerce/v1/user.proto
El resultado es un cliente tipado en TypeScript que importamos directamente. No hay espacio para discrepancias: si el campo se llama user_id en el proto, se llama userId con el casing camelCase generado, pero siempre tipado como bigint porque el proto declara int64.
Implementando el servidor gRPC en Laravel
Laravel no tiene soporte gRPC nativo, pero Roadrunner nos da un worker PHP persistente. El servicio se registra así:
// app/Grpc/Services/UserService.php
namespace App\Grpc\Services;
use App\Grpc\Generated\Ecommerce\V1\UserServiceInterface;
use App\Grpc\Generated\Ecommerce\V1\GetUserRequest;
use App\Grpc\Generated\Ecommerce\V1\GetUserResponse;
use App\Grpc\Generated\Ecommerce\V1\User;
use Spiral\GRPC\ContextInterface;
class UserService implements UserServiceInterface
{
public function GetUser(ContextInterface $ctx, GetUserRequest $in): GetUserResponse
{
// Validación implícita por tipo: $in->getUserId() ya es int64
$userModel = \App\Models\User::findOrFail($in->getUserId());
$user = new User();
$user->setId($userModel->id);
$user->setEmail($userModel->email);
$user->setAge($userModel->age);
$user->setRoles($userModel->roles->pluck('name')->toArray());
$response = new GetUserResponse();
$response->setUser($user);
return $response;
}
public function ListUsers(
ContextInterface $ctx,
ListUsersRequest $in
): \Generator {
foreach (\App\Models\User::cursor() as $model) {
$user = new User();
$user->setId($model->id);
$user->setEmail($model->email);
$response = new ListUsersResponse();
$response->setUser($user);
yield $response; // Streaming server-side
}
}
}
La clave está en que no hay validación manual de tipos. Si alguien envía un string donde el proto exige int64, el parser de Protobuf rechaza el mensaje antes de que llegue al método GetUser. El contrato es la validación.
El proxy gRPC-Web en Cloudflare Workers
Este es el componente que une todo. Cloudflare Workers soportan fetch con HTTP/2 hacia el upstream, lo que nos permite conectar con el servidor gRPC de Laravel sin Envoy.
// worker/src/index.ts
import { grpcWebToGrpc } from './grpc-web-adapter'
export interface Env {
GRPC_BACKEND_HOST: string
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url)
// Solo interceptamos rutas gRPC-Web
if (!url.pathname.startsWith('/ecommerce.v1.')) {
return new Response('Not found', { status: 404 })
}
// Determinar modo: unary o streaming
const contentType = request.headers.get('content-type') || ''
const isStreaming = contentType.includes('grpc-web-text') &&
request.headers.get('x-grpc-web') === '1'
return grpcWebToGrpc(request, env.GRPC_BACKEND_HOST, {
streaming: isStreaming
})
}
}
La función grpcWebToGrpc implementa la traducción del protocolo. gRPC-Web tiene dos formatos: grpc-web-text (base64, para navegadores antiguos) y grpc-web-binary (raw, más eficiente). Nuestro proxy negocia el mejor disponible:
// worker/src/grpc-web-adapter.ts
import { decodeGrpcWebFrame, encodeGrpcFrame } from './codec'
export async function grpcWebToGrpc(
request: Request,
backendHost: string,
options: { streaming: boolean }
): Promise<Response> {
// Decodificar frame gRPC-Web (base64 o binary)
const body = await request.arrayBuffer()
const message = decodeGrpcWebFrame(body)
// Reconstruir headers gRPC nativo
const grpcHeaders = new Headers({
'content-type': 'application/grpc',
'grpc-accept-encoding': 'identity',
'te': 'trailers'
})
// Copiar metadata custom
request.headers.forEach((value, key) => {
if (key.startsWith('x-') || key === 'authorization') {
grpcHeaders.set(key, value)
}
})
// Llamar al backend gRPC via HTTP/2 fetch de Cloudflare
const backendResponse = await fetch(`https://${backendHost}${request.url.pathname}`, {
method: 'POST',
headers: grpcHeaders,
body: encodeGrpcFrame(message.payload),
})
if (options.streaming) {
// Server streaming: chunk el backend, transformar cada frame
const transformStream = new TransformStream({
transform(chunk, controller) {
const webFrame = encodeGrpcWebFrame(chunk, { base64: false })
controller.enqueue(webFrame)
}
})
backendResponse.body?.pipeTo(transformStream.writable)
return new Response(transformStream.readable, {
headers: {
'content-type': 'application/grpc-web+proto',
'grpc-status': '0'
}
})
}
// Unary: respuesta única
const responseBody = await backendResponse.arrayBuffer()
const webFrame = encodeGrpcWebFrame(responseBody, {
base64: request.headers.get('content-type')?.includes('grpc-web-text') || false
})
return new Response(webFrame, {
headers: {
'content-type': request.headers.get('content-type') || 'application/grpc-web+proto',
'grpc-status': backendResponse.headers.get('grpc-status') || '0'
}
})
}
El código se ejecuta en el edge de Cloudflare, típicamente a menos de 50ms del usuario final. El backend gRPC de Laravel puede residir en cualquier región; el proxy maneja la latencia del protocolo, no el negocio.
Consumiendo desde Next.js: el cliente generado
En el frontend usamos directamente el cliente generado. No hay fetch manual ni tipos duplicados:
// nextjs/src/services/user-client.ts
import { UserServiceClient } from '@/grpc/generated/ecommerce/v1/user_pb_service'
import { GetUserRequest, ListUsersRequest } from '@/grpc/generated/ecommerce/v1/user_pb'
const client = new UserServiceClient('/ecommerce.v1.UserService', {
// El fetch interceptor puede agregar tokens de auth
unaryInterceptors: [{
intercept(request, invoker) {
request.getMetadata()['authorization'] = `Bearer ${getToken()}`
return invoker(request)
}
}]
})
export async function fetchUser(userId: bigint): Promise<User> {
const req = new GetUserRequest()
req.setUserId(userId) // TypeScript exige bigint, no number ni string
return new Promise((resolve, reject) => {
client.getUser(req, (err, response) => {
if (err) reject(err)
else resolve(response!.getUser()!)
})
})
}
// Streaming de usuarios
export function streamUsers(callback: (user: User) => void): () => void {
const req = new ListUsersRequest()
const stream = client.listUsers(req)
stream.on('data', (response) => {
callback(response.getUser()!)
})
return () => stream.cancel()
}
Notá la diferencia fundamental con Zod: no hay .parse(), no hay try/catch de validación. Si intentás pasar un number donde el método espera bigint, TypeScript falla en compile time. Si el backend cambia el contrato, el proto generado cambia, y el build del frontend rompe inmediatamente.
Migración progresiva: conviviendo con Zod
Rara vez tenemos el lujo de reescribir todo. En la práctica, migramos endpoint por endpoint. Un patrón útil fue mantener Zod para validaciones de dominio (reglas de negocio que no caben en tipos) y delegar a Protobuf la validación de forma (tipos, obligatoriedad, estructura).
Por ejemplo, en un formulario de registro:
// Validación de forma: Protobuf (generado, estricto)
const protoUser = new ProtoUser()
protoUser.setEmail(email) // debe ser string
// Validación de dominio: Zod para reglas de negocio
const domainRules = z.object({
email: z.string().refine(async (e) => await isEmailUnique(e), {
message: 'Email ya registrado'
}),
age: z.number().refine((a) => a >= 18, {
message: 'Debe ser mayor de edad'
})
})
// Combinación: primero tipo, luego negocio
const partial = { email, age: Number(age) }
await domainRules.parseAsync(partial)
protoUser.setAge(partial.age)
Con el tiempo, las reglas de dominio también migran a lógica del servidor expuesta vía gRPC, y Zod desaparece gradualmente.
Observabilidad: debugging en un mundo binario
JSON es legible; Protobuf no lo es. Para debugging instalamos una interceptor en el worker que opcionalmente loguea en desarrollo:
// En el Worker, condicional sobre environment
if (env.DEBUG_GRPC === 'true') {
console.log('→ gRPC request:', {
method: request.url.pathname,
decoded: MessageType.deserializeBinary(message.payload).toObject()
})
}
En producción usamos los grpc-status y grpc-message trailers para propagar errores estructurados al frontend, sin exponger detalles internos.
Conclusión: contratos como infraestructura
La transición de Zod a Protobuf no fue por moda tecnológica. Fue una decisión arquitectónica: los contratos de tipo fuerte se vuelven parte de la infraestructura, no del código aplicativo. Cloudflare Workers nos permitió eliminar Envoy de la ecuación, reduciendo la superficie operativa. Laravel con Roadrunner nos dio un servidor gRPC performante sin abandonar PHP. Next.js consume servicios tipados como si fueran funciones locales.
El resultado medible: cero errores de deserialización en producción durante los últimos seis meses, reducción del 40% en tamaño de payload respecto al JSON anterior, y eliminación completa de la sincronización manual de tipos entre equipos frontend y backend.
El código fuente completo de esta arquitectura está disponible en nuestro repositorio de referencia, incluyendo los esquemas de Terraform para el despliegue del Worker y la configuración de Roadrunner.