INTEGRITY Dokumentace

← Cloudflare Durable Objects / durable-objects / api

Durable Object Container

Popis

Každý kontejner je spravován Durable Object. Container třída z @cloudflare/containers rozšiřuje DurableObject a stará se za vás o správu životního cyklu, připravenost portů a časové limity uspání. Durable Object řídí směrování, trvalý stav a háčky životního cyklu, zatímco proces kontejneru spouští váš image uvnitř Linux VM.

Nízkoúrovňové API popsané na této stránce je dostupné na this.ctx.container uvnitř libovolné třídy Durable Object, která má container binding. Použijte ji, pokud potřebujete přímou kontrolu nad procesem kontejneru nebo nemůžete použít Container třídu.

Protože Container třída rozšiřuje DurableObject, máte také přístup k Úložiště SQLite prostřednictvím this.ctx.storage, alarmy, a všechna ostatní API Durable Objects.

index.js
export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);

		// boot the container when starting the DO
		this.ctx.blockConcurrencyWhile(async () => {
			this.ctx.container.start();
		});
	}
}
index.ts
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);

    	// boot the container when starting the DO
    	this.ctx.blockConcurrencyWhile(async () => {
    		this.ctx.container.start();
    });
    }

}

Atributy

running

running vrací true pokud kontejner aktuálně běží. Nezaručuje to, že se kontejner zcela spustil a je připraven přijímat požadavky.

	this.ctx.container.running;

Metody

start

start spustí kontejner. Tato metoda neblokuje, dokud není kontejner plně spuštěný. Před jeho použitím možná budete chtít ověřit, že je kontejner připraven přijímat požadavky.

this.ctx.container.start({
	env: {
		FOO: "bar",
	},
	enableInternet: false,
	entrypoint: ["node", "server.js"],
});

Parametry

Návratové hodnoty

exec

exec spustí další proces uvnitř již běžícího kontejneru. Nespustí zastavený kontejner.

Následující příklad volá this.ctx.container.exec() uvnitř třídy, která rozšiřuje Container z @cloudflare/containers. V metodách RPC zkontrolujte this.ctx.container.running a volejte await this.start() v případě potřeby. Můžete také použít onStart() hook pro spuštění libovolné sady příkazů při každém startu kontejneru.

exec(
  cmd: string[],
  options?: ContainerExecOptions,
): Promise<ExecProcess>

exec operace spustí spustitelný soubor přímo se zadanými argumenty. Nespouští shell a neinterpretuje roury, přesměrování, expanzi ani jinou syntaxi shellu. Bash spusťte explicitně pomocí ["bash", "-lc", "<COMMAND>"] pokud Bash v obrazu existuje. Použijte ["sh", "-c", "<COMMAND>"] pro obrazy, které mají pouze shell Portable Operating System Interface (POSIX).

Následující metoda RPC spustí Container před provedením příkazu:

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
	async runCommand() {
		if (!this.ctx.container.running) {
			await this.start();
		}

		const process = await this.ctx.container.exec(["node", "--version"]);
		const output = await process.output();

		return {
			pid: process.pid,
			exitCode: output.exitCode,
			stdout: new TextDecoder().decode(output.stdout),
		};
	}
}
import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
	async runCommand() {
		if (!this.ctx.container.running) {
			await this.start();
		}

		const process = await this.ctx.container.exec(["node", "--version"]);
		const output = await process.output();

		return {
			pid: process.pid,
			exitCode: output.exitCode,
			stdout: new TextDecoder().decode(output.stdout),
		};
	}
}

Parametry

Návratové hodnoty

Vrátí Promise<ExecProcess>.

ExecProcess má tato pole a metody:

S stderr: "combined", stderr je null na ExecProcess a prázdný ArrayBuffer na ExecOutput. Přečtěte oba výstupní kanály z stdout.

output() vyvolá TypeError pokud se zavolá vícekrát nebo poté, co se z některého ze čitelných proudů začne číst. U velkých výstupů čtěte oba čitelné proudy souběžně, místo abyste je ukládali do vyrovnávací paměti pomocí output().

exec nemá žádný vestavěný časový limit. Použijte kill() pro vyžádání ukončení, poté sledujte dokončení pomocí exitCode. Proces může signál zpracovat nebo ignorovat, takže to nevynucuje pevný časový limit. Z daného signálu nevyvozujte konkrétní kód ukončení.

Výjimky

Příklady zaměřené na konkrétní úlohy najdete v Spouštění příkazů.

destroy

destroy zastaví kontejner a volitelně vrátí vlastní chybovou zprávu monitor() chybový callback.

this.ctx.container.destroy("Manually Destroyed");

Parametry

Návratové hodnoty

signal

signal odešle kontejneru signál IPC, například SIGKILL nebo SIGTERM. To se hodí pro ukončení kontejneru, ať už řízené, nebo vynucené.

const SIGTERM = 15;
this.ctx.container.signal(SIGTERM);

Parametry

Návratové hodnoty

getTcpPort

getTcpPort vrátí TCP port z kontejneru. Ten lze použít ke komunikaci s kontejnerem přes TCP a HTTP.

const port = this.ctx.container.getTcpPort(8080);
const res = await port.fetch("http://container/set-state", {
	body: initialState,
	method: "POST",
});
const conn = this.ctx.container.getTcpPort(8080).connect("10.0.0.1:8080");
await conn.opened;

try {
	if (request.body) {
		await request.body.pipeTo(conn.writable);
	}
	return new Response(conn.readable);
} catch (err) {
	console.error("Request body piping failed:", err);
	return new Response("Failed to proxy request body", { status: 502 });
}

Parametry

Návratové hodnoty

monitor

monitor vrátí promise, který se splní po ukončení kontejneru a skončí chybou, pokud kontejner selže. To se hodí k nastavení callbacků, které v kódu Workeru reagují na změny stavu kontejneru.

class MyContainer extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);
		function onContainerExit() {
			console.log("Container exited");
		}

		// the "err" value can be customized by the destroy() method
		async function onContainerError(err) {
			console.log("Container errored", err);
		}

		this.ctx.container.start();
		this.ctx.container.monitor().then(onContainerExit).catch(onContainerError);
	}
}

Parametry

Návratové hodnoty

interceptOutboundHttp

interceptOutboundHttp směruje odchozí HTTP požadavky odpovídající hostname, glob vzoru hostname, IP adrese, kombinaci IP:port nebo rozsahu CIDR přes WorkerEntrypoint. Lze volat před spuštěním kontejneru i po něm. Otevřená spojení převezmou nový handler, aniž by došlo k jejich přerušení.

const worker = this.ctx.exports.MyWorker({ props: { message: "hello" } });

// Match a specific hostname
this.ctx.container.interceptOutboundHttp("api.example.com", worker);

// Match a hostname glob pattern
this.ctx.container.interceptOutboundHttp("*.example.com", worker);

// Match an IP:port
await this.ctx.container.interceptOutboundHttp("15.0.0.1:80", worker);

// Match a CIDR range (IPv4 and IPv6)
await this.ctx.container.interceptOutboundHttp("123.123.123.123/23", worker);

Parametry

Návratové hodnoty

interceptAllOutboundHttp

interceptAllOutboundHttp směruje veškeré odchozí HTTP požadavky z kontejneru přes WorkerEntrypoint, bez ohledu na cíl.

await this.ctx.container.interceptAllOutboundHttp(worker);

Parametry

Návratové hodnoty

interceptOutboundHttps

interceptOutboundHttps směruje odchozí HTTPS požadavky odpovídající hostname nebo glob vzoru hostname přes WorkerEntrypoint. Funguje stejně jako interceptOutboundHttp ale pro provoz HTTPS. Kontejner musí důvěřovat certifikátu CA na /etc/cloudflare/certs/cloudflare-containers-ca.crt aby fungovalo zachytávání HTTPS.

Podporuje glob vzory, kde * odpovídá libovolné posloupnosti znaků.

const worker = this.ctx.exports.MyWorker({ props: {} });

// Match a specific hostname
this.ctx.container.interceptOutboundHttps("api.example.com", worker);

// Match a hostname glob pattern
this.ctx.container.interceptOutboundHttps("*.example.com", worker);

// Intercept all HTTPS traffic
this.ctx.container.interceptOutboundHttps("*", worker);

Parametry

Návratové hodnoty