← Sandbox SDK / sandbox / api

Porty

Zpřístupněte služby běžící ve vašem sandboxu přes veřejné náhledové URL adresy. Viz Koncept URL adres náhledu s podrobnostmi.

Funkce modulu

`proxyToSandbox()`

Směruje příchozí požadavky HTTP a WebSocket do správného sandboxového kontejneru. Zavolejte ji na začátku svého Workeru, ve funkci fetch handler, před veškerou logikou aplikace, aby automaticky zachytával a přeposílal požadavky na preview URL.

proxyToSandbox(request: Request, env: Env): Promise<Response | null>

Parametry:

request - Příchozí Request objekt z fetch handler.
env - Env objekt obsahující vaši vazbu Sandbox.

Vrací: Promise<Response | null> : Response pokud požadavek odpovídal preview URL a byl směrován do sandboxu, nebo null pokud požadavek neodpovídal a měla by ho zpracovat logika vaší aplikace.

Funkce zkontroluje hostname požadavku a zjistí, zda odpovídá vzoru subdomény exponovaného portu, například 8080-sandbox-id-token.yourdomain.com). Pokud odpovídá, proxyToSandbox() přesměruje požadavek na správný Durable Object a zpracuje ho služba sandboxu. Podporovány jsou požadavky HTTP i WebSocket upgrade.

import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

export default {
	async fetch(request, env) {
		// Always call proxyToSandbox first to handle preview URL requests
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;

		// Your application routes
		const sandbox = getSandbox(env.Sandbox, "my-sandbox");
		// ...
		return new Response("Not found", { status: 404 });
	},
};

import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Always call proxyToSandbox first to handle preview URL requests
    const proxyResponse = await proxyToSandbox(request, env);
    if (proxyResponse) return proxyResponse;

    // Your application routes
    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
    // ...
    return new Response('Not found', { status: 404 });
  }
};

Metody

`exposePort()`

Zpřístupněte port a získejte náhledovou URL adresu pro přístup ke službám běžícím v sandboxu.

const response = await sandbox.exposePort(port: number, options: ExposePortOptions): Promise<ExposePortResponse>

Parametry:

port - Číslo portu ke zpřístupnění (1024-65535)
options:
- hostname - Doménový název vašeho Workeru (např. 'example.com'). Vyžadováno pro sestavení náhledových URL se zástupnými subdoménami, například https://8080-sandbox-abc123token.example.com. Nemůže to být .workers.dev doména, protože nepodporuje zástupné vzory DNS.
- name - Popisný název portu (volitelné)
- token - Vlastní token pro náhledovou URL (nepovinné). Musí mít 1 až 16 znaků a obsahovat pouze malá písmena (a-z), číslice (0-9), spojovníky (-) a podtržítka (_). Pokud není zadán, automaticky se vygeneruje náhodný 16znakový token.

Vrací: Promise<ExposePortResponse> hodnotou port, url (preview URL), name

// Extract hostname from request
const { hostname } = new URL(request.url);

// Basic usage with auto-generated token
await sandbox.startProcess("python -m http.server 8000");
const exposed = await sandbox.exposePort(8000, { hostname });

console.log("Available at:", exposed.url);
// https://8000-sandbox-id-abc123random.yourdomain.com

// With custom token for stable URLs across restarts
const stable = await sandbox.exposePort(8080, {
	hostname,
	token: "my_service_v1", // 1-16 chars: a-z, 0-9, _
});
console.log("Stable URL:", stable.url);
// https://8080-sandbox-id-my_service_v1.yourdomain.com

// With custom token for stable URLs across deployments
await sandbox.startProcess("node api.js");
const api = await sandbox.exposePort(3000, {
	hostname,
	name: "api",
	token: "prod-api-v1", // URL stays same across restarts
});

console.log("Stable API URL:", api.url);
// https://3000-sandbox-id-prod-api-v1.yourdomain.com

// Multiple services with custom tokens
await sandbox.startProcess("npm run dev");
const frontend = await sandbox.exposePort(5173, {
	hostname,
	name: "frontend",
	token: "dev-ui",
});

// Extract hostname from request
const { hostname } = new URL(request.url);

// Basic usage with auto-generated token
await sandbox.startProcess('python -m http.server 8000');
const exposed = await sandbox.exposePort(8000, { hostname });

console.log('Available at:', exposed.url);
// https://8000-sandbox-id-abc123random.yourdomain.com

// With custom token for stable URLs across restarts
const stable = await sandbox.exposePort(8080, {
  hostname,
  token: 'my_service_v1' // 1-16 chars: a-z, 0-9, _
});
console.log('Stable URL:', stable.url);
// https://8080-sandbox-id-my_service_v1.yourdomain.com

// With custom token for stable URLs across deployments
await sandbox.startProcess('node api.js');
const api = await sandbox.exposePort(3000, {
  hostname,
  name: 'api',
  token: 'prod-api-v1'  // URL stays same across restarts
});

console.log('Stable API URL:', api.url);
// https://3000-sandbox-id-prod-api-v1.yourdomain.com

// Multiple services with custom tokens
await sandbox.startProcess('npm run dev');
const frontend = await sandbox.exposePort(5173, {
  hostname,
  name: 'frontend',
  token: 'dev-ui'
});

Vlastní tokeny pro stabilní URL adresy

Vlastní tokeny zajišťují stejné náhledové URL adresy i po restartech kontejneru a novém nasazení. Hodí se to pro:

Produkční prostředí - Sdílení stabilních URL adres s uživateli nebo týmy
Vývojové pracovní postupy - Udržujte záložky a integrace
CI/CD pipeliny - Odkazování na konzistentní URL adresy v testech nebo nasazovacích skriptech

Požadavky na token:

délka 1-16 znaků
Pouze malá písmena (a-z), číslice (0-9), spojovníky (-) a podtržítka (_)
Musí být jedinečné pro každý sandbox (tokeny nelze používat opakovaně napříč různými porty)

// Production API with stable URL
const { url } = await sandbox.exposePort(8080, {
	hostname: "api.example.com",
	token: "v1-stable", // Always the same URL
});

// Error: Token collision prevention
await sandbox.exposePort(8081, { hostname, token: "v1-stable" });
// Throws: Token 'v1-stable' is already in use by port 8080

// Success: Re-exposing same port with same token (idempotent)
await sandbox.exposePort(8080, { hostname, token: "v1-stable" });
// Works - same port, same token

// Production API with stable URL
const { url } = await sandbox.exposePort(8080, {
  hostname: 'api.example.com',
  token: 'v1-stable'  // Always the same URL
});

// Error: Token collision prevention
await sandbox.exposePort(8081, { hostname, token: 'v1-stable' });
// Throws: Token 'v1-stable' is already in use by port 8080

// Success: Re-exposing same port with same token (idempotent)
await sandbox.exposePort(8080, { hostname, token: 'v1-stable' });
// Works - same port, same token

`validatePortToken()`

Ověří, zda je token oprávněn přistupovat ke konkrétnímu exponovanému portu. Užitečné pro vlastní autentizaci nebo směrovací logiku.

const isValid = await sandbox.validatePortToken(port: number, token: string): Promise<boolean>

Parametry:

port - Číslo portu ke kontrole
token - Token k ověření

Vrací: Promise<boolean> - true pokud je token platný pro daný port, false jinak

// Custom validation in your Worker
export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		// Extract token from custom header or query param
		const customToken = request.headers.get("x-access-token");

		if (customToken) {
			const sandbox = getSandbox(env.Sandbox, "my-sandbox");
			const isValid = await sandbox.validatePortToken(8080, customToken);

			if (!isValid) {
				return new Response("Invalid token", { status: 403 });
			}
		}

		// Handle preview URL routing
		const proxyResponse = await proxyToSandbox(request, env);
		if (proxyResponse) return proxyResponse;

		// Your application routes
		return new Response("Not found", { status: 404 });
	},
};

// Custom validation in your Worker
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    
    // Extract token from custom header or query param
    const customToken = request.headers.get('x-access-token');
    
    if (customToken) {
      const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
      const isValid = await sandbox.validatePortToken(8080, customToken);
      
      if (!isValid) {
        return new Response('Invalid token', { status: 403 });
      }
    }
    
    // Handle preview URL routing
    const proxyResponse = await proxyToSandbox(request, env);
    if (proxyResponse) return proxyResponse;
    
    // Your application routes
    return new Response('Not found', { status: 404 });
  }
};

`unexposePort()`

Odebere exponovaný port a zavře jeho URL adresu náhledu.

await sandbox.unexposePort(port: number): Promise<void>

Parametry:

port - Číslo portu ke zrušení zpřístupnění

await sandbox.unexposePort(8000);

await sandbox.unexposePort(8000);

`getExposedPorts()`

Získejte informace o všech aktuálně zpřístupněných portech.

const response = await sandbox.getExposedPorts(): Promise<GetExposedPortsResponse>

Vrací: Promise<GetExposedPortsResponse> hodnotou ports pole (obsahující port, url, name)

const { ports } = await sandbox.getExposedPorts();

for (const port of ports) {
	console.log(`${port.name || port.port}: ${port.url}`);
}

const { ports } = await sandbox.getExposedPorts();

for (const port of ports) {
  console.log(`${port.name || port.port}: ${port.url}`);
}

`wsConnect()`

Připojte se k WebSocket serverům běžícím v sandboxu. Použijte to ve chvíli, kdy váš Worker potřebuje navázat WebSocket spojení se službami v sandboxu.

Běžné případy použití:

Směrování příchozích WebSocket upgrade požadavků s vlastní autentizací nebo autorizací
Připojte se ze svého Workeru a získejte data v reálném čase ze služeb sandboxu

Pro zpřístupnění služeb WebSocket přes veřejné preview URL použijte exposePort() hodnotou proxyToSandbox() místo toho. Viz Průvodce připojeními WebSocket příklady.

const response = await sandbox.wsConnect(request: Request, port: number): Promise<Response>

Parametry:

request - Příchozí požadavek na upgrade WebSocket
port - Číslo portu (1024-65535, kromě 3000)

Vrací: Promise<Response> - Odpověď WebSocket, která naváže spojení

import { getSandbox } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

export default {
	async fetch(request, env) {
		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") {
			const sandbox = getSandbox(env.Sandbox, "my-sandbox");
			return await sandbox.wsConnect(request, 8080);
		}

		return new Response("WebSocket endpoint", { status: 200 });
	},
};

import { getSandbox } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
      const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
      return await sandbox.wsConnect(request, 8080);
    }

    return new Response('WebSocket endpoint', { status: 200 });
  }
};

Koncept URL adres náhledu - Jak fungují náhledové URL adresy
Průvodce zpřístupněním služeb - Kompletní postup pro spouštění služeb, zpřístupnění portů a směrování požadavků
Průvodce připojeními WebSocket - Směrování WebSocket přes náhledové URL adresy
Commands API - Spouštění procesů na pozadí
Tunnels API - Bez nutnosti konfigurace *.trycloudflare.com URL pro rychlý vývoj

Porty

Funkce modulu

proxyToSandbox()

Metody

exposePort()

Vlastní tokeny pro stabilní URL adresy

validatePortToken()

unexposePort()

getExposedPorts()

wsConnect()

Související zdroje

`proxyToSandbox()`

`exposePort()`

`validatePortToken()`

`unexposePort()`

`getExposedPorts()`

`wsConnect()`