Runtime API

Эта страница фиксирует текущий публичный runtime contract. В beta основной типизированный API доступен внутри ONREZA Functions через явный объект ctx. Для Compute-приложений используйте стандартные API вашего runtime: process.env, fetch, файловую систему в разрешённых пределах и обычные HTTP-запросы.

ONREZA Functions ctx

Function handler получает ctx вторым аргументом:

export default {
  async fetch(request, ctx) {
    await ctx.log.info("request", {
      path: new URL(request.url).pathname,
      invocationId: ctx.invocation.id,
    });

    return Response.json({ ok: true });
  },
};

Binding	Для чего используется
`ctx.env`	Environment variables текущего окружения.
`ctx.kv`	Key-value storage окружения: `get`, `put`/`set`, `incr`, `delete`, `list`.
`ctx.sql`	Managed PostgreSQL tagged-template binding, если к проекту подключена ровно одна active БД.
`ctx.log`	Structured logs функции.
`ctx.trace`	Short diagnostic spans/events внутри invocation.
`ctx.locals`	Передача данных между шагами одного route pipeline.
`ctx.waitUntil()`	Короткий side effect после формирования response.

Подробнее: ONREZA Functions.

Environment Variables

В Compute-приложениях переменные доступны стандартно:

const databaseUrl = process.env.DATABASE_URL;

В ONREZA Functions используйте ctx.env, чтобы не зависеть от ambient runtime state:

export default {
  async fetch(_request, ctx) {
    const apiUrl = ctx.env.API_URL;
    return Response.json({ apiUrlConfigured: Boolean(apiUrl) });
  },
};

Переменные scoped по окружению: production-функция видит production values, preview-функция — preview values.

KV Store

Текущий публичный runtime-доступ к KV — ctx.kv в ONREZA Functions:

const encoder = new TextEncoder();
const decoder = new TextDecoder();

await ctx.kv.set("session:123", JSON.stringify({ userId: "u_123" }), {
  ttl: 3600,
});

const raw = await ctx.kv.get("session:123");
const session = raw ? JSON.parse(decoder.decode(raw)) : null;

const count = await ctx.kv.incr("rate:ip:203.0.113.10", { ttl: 60 });
if (count > 60) {
  return new Response("Too Many Requests", { status: 429 });
}

const page = await ctx.kv.list({ prefix: "session:", limit: 100 });
await Promise.all(page.keys.map((key) => ctx.kv.delete(key)));

Подробнее: KV Store.

Managed PostgreSQL

ctx.sql доступен, когда у проекта есть ровно одна active managed PostgreSQL attachment. Binding выглядит как tagged template и параметризует значения:

const rows = await ctx.sql<{ id: string; email: string }>`
  select id, email
  from users
  where id = ${userId}
`;

Если БД не привязана, привязано несколько БД или БД ещё не active, binding возвращает customer-safe ошибку вместо silent fallback.

Image Optimization URL

Оптимизация изображений работает через endpoint:

/_onreza/image?url=/images/hero.jpg&w=1280&q=75

Если нужен helper в серверном коде, держите его рядом с приложением:

const IMAGE_WIDTHS = [
  16, 32, 48, 64, 96, 128, 160, 192, 256, 320, 384, 512, 640, 768, 832,
  1024, 1152, 1280, 1536, 1920, 2048, 2560, 3072, 3840, 4096,
] as const;

function imageUrl(src: string, options: { width: number; quality?: number }) {
  if (!src.startsWith("/") || src.includes("..")) {
    throw new Error("Image URL must be a safe relative path");
  }

  const width = IMAGE_WIDTHS.find((candidate) => candidate >= options.width) ?? 4096;
  const params = new URLSearchParams({
    url: src,
    w: String(width),
    q: String(options.quality ?? 75),
  });

  return `/_onreza/image?${params}`;
}

Подробнее: Image Optimization.