Acceder al objeto: el stub, el RPC y dónde vive

Ya nombras objetos y entiendes por qué son únicos y seguros. Ahora, cómo se les habla. La respuesta corta es de una elegancia engañosa: obtienes un stub y llamas sus métodos con await, como si el objeto viviera en tu mismo proceso. La respuesta larga esconde una verdad que hemos ido aplazando lección tras lección —un Durable Object vive en un único lugar del planeta, y todas las llamadas convergen allí—. El stub disimula la distancia, pero no la abole: conocerla es lo que separa a quien invoca un objeto de quien diseña dónde debe posarse su gravedad.

Del binding al stub

El camino tiene dos peldaños que ya conoces: del namespace sacas un id, y del id sacas el stub.

const id = env.CONTADOR.idFromName("global");
const stub = env.CONTADOR.get(id);

El stub es un proxy del lado del cliente: un asa local que representa a un objeto remoto que puede estar a miles de kilómetros. Tener el stub no instancia nada pesado en tu Worker ni reserva memoria en tu isolate; es una referencia, ligera y barata. El objeto real se crea —o se despierta de su hibernación— de forma perezosa, en la primera llamada que le hagas, no al obtener el stub.

Esta pereza importa: puedes obtener stubs a discreción, guardarlos, pasarlos, sin coste. El gasto llega cuando de verdad hablas con el objeto, y solo entonces la plataforma lo materializa donde le corresponde.

Y como el stub es solo una referencia, puedes reutilizarlo para varias llamadas seguidas dentro de la misma invocación, o volver a pedirlo cuando lo necesites: no hay conexión que amortizar ni pool que gestionar. El objeto pesado vive al otro lado; tú solo sostienes un asa ligera hacia él.

Llamar sus métodos: RPC o fetch

Con un Durable Object moderno —el que extiende DurableObject— sus métodos públicos son invocables por RPC directamente, como si fueran locales. Le pones un await delante y ya está:

export default {
  async fetch(request, env): Promise<Response> {
    const id = env.CONTADOR.idFromName("global");
    const stub = env.CONTADOR.get(id);
    const total = await stub.incrementar(); // RPC transparente
    return Response.json({ total });
  },
} satisfies ExportedHandler<Env>;

El RPC es transparente: los argumentos y el valor de retorno viajan serializados, y el runtime enruta la llamada hasta donde viva el objeto, sin que tú construyas una petición ni parsees una respuesta. Lees el código como una llamada a un método porque ese es, exactamente, el modelo mental correcto: un objeto con métodos, que resulta estar lejos.

La vía antigua es fetch. El objeto implementa fetch(request) y tú lo invocas con stub.fetch(request), entregando un Request y recibiendo un Response. Es más ceremoniosa —empaquetas y desempaquetas a mano— pero sigue siendo la puerta obligada para lo que es intrínsecamente una petición HTTP: sobre todo, abrir un WebSocket contra el objeto, que se negocia con un upgrade sobre fetch.

Dónde vive físicamente

Aquí está el hecho que todas las lecciones anteriores dieron por sabido sin decirlo: un Durable Object es un único punto en el espacio. Cuando se accede a él por primera vez, la plataforma lo instancia en un centro de datos —por defecto, cerca de quien lo invoca primero, o guiado por una pista de ubicación— y allí se queda. Desde ese momento, cada llamada, venga de donde venga, se enruta a ese hogar. El objeto no está en todas partes como el Worker: está en un sitio.

// una pista de ubicacion al obtener el stub
const id = env.SALA.idFromName("sala:eu-42");
const stub = env.SALA.get(id, { locationHint: "weur" });

flowchart LR
U[usuario en Lima] --> W[Worker cercano en Lima]
W --> DO[Durable Object en Frankfurt]
DO --> ST[storage coubicado]
style DO fill:#f9e2af,color:#11111b
style ST fill:#a6e3a1,color:#11111b

Esto reintroduce, ahora concreta, la tensión del primer nivel de la guía: el cómputo del Worker está cerca del usuario, pero esta pieza de estado está en un lugar. Hay una asimetría de latencia real: un usuario en Lima habla con un Worker en Lima, pero si el objeto vive en Fráncfort, ese salto lo paga. La buena noticia es que el objeto y su almacenamiento están coubicados, así que el objeto conversa con sus propios datos a velocidad de memoria; el coste de red es el salto del Worker al objeto, pagado una vez por llamada externa, no una vez por cada lectura de estado.

La consecuencia de diseño es que la colocación importa. Un location hint te deja empujar el objeto hacia la región donde viven los usuarios o los sistemas que más lo usan, para que ese único salto sea lo más corto posible. No hay una respuesta universal: coloca cada objeto cerca de su centro de gravedad, allí donde converge la mayoría de quienes lo necesitan.

Y ese centro de gravedad no siempre es el usuario. Si dos objetos conversan mucho entre sí —el de una partida y el de cada jugador—, o si un objeto escribe sin cesar a un almacén regional, acercarlo a esos interlocutores puede pesar más que acercarlo a las personas. La gravedad apunta a donde está el diálogo más intenso, sean usuarios, otros objetos o datos.