Types

Tipos da Azion Lib no pacote @aziontech/types para handlers de function, a requisição e seus metadados e o contexto do handler.

Última atualização

Ver como Markdown Configurar agente

O pacote @aziontech/types é a biblioteca da Azion Lib de tipos TypeScript para código que roda no Azion Runtime. Ele declara os formatos de handler de uma function, a requisição com seus metadados e o contexto que um handler recebe. O pacote contém apenas tipos: seu módulo JavaScript não exporta nada e não faz nenhuma chamada de API, por isso você importa cada nome com import type.

Instale o pacote:

npm install @aziontech/types

Os exemplos em TypeScript desta página importam seus tipos com import type. O exemplo de metadados roda no Node.js, e os exemplos de handler rodam dentro de uma function servida localmente com o azion dev.

nota — No azion dev, request.metadata não existe, por isso os exemplos de handler desta página o leem com optional chaining (metadata?.). Localmente, um handler firewall de módulo recebe um ctx que contém apenas waitUntil. Para os metadados que uma function com deploy feito lê, consulte API de metadados.

AzionRuntimeRequestMetadata

O objeto de metadados que AzionRuntimeRequest carrega em metadata. A interface declara 26 chaves, todas do tipo string e obrigatórias, mais uma assinatura de índice de string que tipa qualquer outra chave.

PropriedadeTipoObrigatórioDescrição
geoip_asnstringSimNúmero do sistema autônomo.
geoip_citystringSimCódigo da cidade.
geoip_city_continent_codestringSimCódigo do continente da cidade.
geoip_city_country_codestringSimCódigo do país da cidade.
geoip_city_country_namestringSimNome do país da cidade.
geoip_continent_codestringSimCódigo do continente.
geoip_country_codestringSimCódigo do país.
geoip_country_namestringSimNome do país.
geoip_regionstringSimCódigo da região.
geoip_region_namestringSimNome da região.
remote_addrstringSimEndereço IP do cliente.
remote_portstringSimPorta TCP do cliente.
remote_userstringSimUsuário informado na URL.
server_protocolstringSimProtocolo da requisição.
server_fingerprintstringSimFingerprint TLS do servidor.
server_fingerprint_ja4hstringSimFingerprint JA4H do servidor.
ssl_cipherstringSimCifra TLS da sessão.
ssl_protocolstringSimProtocolo TLS da sessão.
client_fingerprintstringSimFingerprint do cliente.
client_idstringSimIdentificador da conta Azion dona do workload.
configuration_idstringSimIdentificador do workload que recebeu a requisição.
edge_connector_idstringSim—
function_idstringSimIdentificador da function que roda para a requisição.
http_ssl_ja4stringSimFingerprint TLS JA4 da requisição.
request_idstringSimID único da requisição.
solution_idstringSimIdentificador interno da solução que trata a requisição.
[key: string]stringNãoQualquer outra chave do objeto.

Um objeto literal tipado como AzionRuntimeRequestMetadata precisa carregar as 26 chaves, ou o tsc para com o erro TS2740 e nomeia as que faltam. Para tipar um objeto que contém parte das chaves, envolva a interface em Partial.

Este exemplo monta um objeto de metadados com 16 das chaves:

TypeScript
01import type { AzionRuntimeRequestMetadata } from '@aziontech/types';
02
03const requestMetadata: Partial<AzionRuntimeRequestMetadata> = {
04 geoip_asn: '12345',
05 geoip_city: 'Sao Paulo',
06 geoip_city_continent_code: 'SA',
07 geoip_city_country_code: 'BR',
08 geoip_city_country_name: 'Brazil',
09 geoip_continent_code: 'SA',
10 geoip_country_code: 'BR',
11 geoip_country_name: 'Brazil',
12 geoip_region: 'SP',
13 geoip_region_name: 'Sao Paulo',
14 remote_addr: '192.0.2.1',
15 remote_port: '443',
16 remote_user: 'user',
17 server_protocol: 'HTTP/1.1',
18 ssl_cipher: 'ECDHE-RSA-AES128-GCM-SHA256',
19 ssl_protocol: 'TLSv1.2',
20};
21console.log(Object.keys(requestMetadata).length, 'fields');

Saída:

16 fields

AzionRuntimeRequest

A requisição que um handler de módulo recebe: o Request padrão com uma propriedade metadata.

TypeScript
01type AzionRuntimeRequest = Request & {
02 metadata: AzionRuntimeRequestMetadata;
03};
PropriedadeTipoObrigatórioDescrição
metadataAzionRuntimeRequestMetadataSimOs metadados da requisição.

AzionRuntimeModule

O export padrão de uma function no formato de módulo: um objeto com um handler fetch, um handler firewall ou ambos. O formato de módulo é o formato de handler que Handlers recomenda.

TypeScript
01interface AzionRuntimeModule {
02 fetch?: (request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>;
03 firewall?: (request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>;
04}
PropriedadeTipoObrigatórioDescrição
fetch(request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>NãoO handler que o Azion Runtime chama para uma requisição.
firewall(request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>NãoO handler de firewall, como o tipo o declara.

Esta function verifica seu export padrão contra o tipo com satisfies e responde com a cidade do cliente:

TypeScript
01import type { AzionRuntimeModule, AzionRuntimeRequest } from '@aziontech/types';
02
03export default {
04 async fetch(request: AzionRuntimeRequest): Promise<Response> {
05 const { metadata } = request;
06 console.log('Request URL:', request.url);
07 console.log('Client IP:', metadata?.remote_addr);
08 console.log('GeoIP City:', metadata?.geoip_city);
09 return new Response(`Hello from ${metadata?.geoip_city ?? 'an unknown city'}\n`);
10 },
11} satisfies AzionRuntimeModule;

Com a function servida localmente com azion dev, em que a requisição não carrega metadados, uma requisição retorna:

Texto
01$ curl http://localhost:3333/types
02HTTP/1.1 200 OK
03content-type: text/plain;charset=UTF-8
04
05Hello from an unknown city

A function registra no log:

Texto
01Request URL: http://localhost:3333/types
02Client IP: undefined
03GeoIP City: undefined

AzionRuntimeCtx

O contexto que AzionRuntimeModule declara como terceiro argumento dos dois handlers.

TypeScript
01interface AzionRuntimeCtx {
02 waitUntil: (promise: Promise<unknown>) => void;
03 args?: Record<string, unknown>;
04}
PropriedadeTipoObrigatórioDescrição
waitUntil(promise: Promise<unknown>) => voidSimEstende a execução até que promise seja resolvida ou rejeitada.
argsRecord<string, unknown>NãoOs args da function instance.

AzionFetchEvent

O evento que um listener registrado com addEventListener para o tipo fetch recebe. Ele estende o Event padrão.

TypeScript
01interface AzionFetchEvent extends Event {
02 request: Request & {
03 metadata: AzionRuntimeRequestMetadata;
04 };
05 waitUntil: (promise: Promise<unknown>) => void;
06 respondWith: (response: Response | Promise<Response>) => void;
07}
PropriedadeTipoObrigatórioDescrição
requestRequest & { metadata: AzionRuntimeRequestMetadata }SimA requisição, com seus metadados.
waitUntil(promise: Promise<unknown>) => voidSimDeclarado pelo tipo.
respondWith(response: Response | Promise<Response>) => voidSimDefine a resposta que a function envia ao cliente.

Em uma function JavaScript, um comentário JSDoc aplica o tipo ao evento. Este listener responde com a cidade do cliente:

JavaScript
01/** @typedef {import('@aziontech/types').AzionFetchEvent} AzionFetchEvent */
02
03addEventListener('fetch', (/** @type {AzionFetchEvent} */ event) => {
04 const { request } = event;
05 const metadata = request.metadata;
06
07 console.log('Request URL:', request.url);
08 console.log('Client IP:', metadata?.remote_addr);
09 console.log('GeoIP City:', metadata?.geoip_city);
10
11 event.respondWith(new Response(`Hello from ${metadata?.geoip_city ?? 'an unknown city'}\n`));
12});

Com a function servida localmente com azion dev, o listener retorna a mesma resposta do exemplo de AzionRuntimeModule e registra no log as mesmas três linhas:

Texto
01$ curl http://localhost:3333/types
02HTTP/1.1 200 OK
03content-type: text/plain;charset=UTF-8
04
05Hello from an unknown city

FetchEventListener

O tipo de um listener para o evento fetch.

type FetchEventListener = (event: AzionFetchEvent, args?: Record<string, unknown>) => void | Promise<void>;
ParâmetroTipoObrigatórioDescrição
eventAzionFetchEventSimO evento fetch.
argsRecord<string, unknown>NãoOs args que o listener recebe.

AzionFirewallEvent

O tipo de evento que o pacote declara para um listener de firewall. Ele estende AzionFetchEvent com três métodos.

TypeScript
01interface AzionFirewallEvent extends AzionFetchEvent {
02 deny: () => void;
03 drop: () => void;
04 continue: () => void;
05}
PropriedadeTipoObrigatórioDescrição
deny() => voidSimDeclarado pelo tipo.
drop() => voidSimDeclarado pelo tipo.
continue() => voidSimDeclarado pelo tipo.
request, waitUntil, respondWithcomo em AzionFetchEventSimHerdados de AzionFetchEvent.

AzionRuntimeFirewallCtx

O tipo de contexto que o pacote declara para módulos de firewall. Ele estende AzionRuntimeCtx com três métodos. AzionRuntimeModule tipa o ctx do seu handler firewall como AzionRuntimeCtx, não como este tipo.

TypeScript
01interface AzionRuntimeFirewallCtx extends AzionRuntimeCtx {
02 deny: () => void;
03 continue: () => void;
04 drop: () => void;
05}
PropriedadeTipoObrigatórioDescrição
deny() => voidSimDeclarado pelo tipo.
continue() => voidSimDeclarado pelo tipo.
drop() => voidSimDeclarado pelo tipo.
waitUntil(promise: Promise<unknown>) => voidSimHerdado de AzionRuntimeCtx.
argsRecord<string, unknown>NãoHerdado de AzionRuntimeCtx.

FirewallEventListener

O tipo de um listener para o evento de firewall.

type FirewallEventListener = (event: AzionFirewallEvent, args?: Record<string, unknown>) => void | Promise<void>;
ParâmetroTipoObrigatórioDescrição
eventAzionFirewallEventSimO evento de firewall.
argsRecord<string, unknown>NãoOs args que o listener recebe.

Namespace Azion

O pacote também exporta o namespace Azion, que declara os namespaces Azion.Storage e Azion.Sql. Para as APIs do runtime que esses nomes descrevem, consulte Object Storage API e SQL Database API.

TypeScript
01declare namespace Azion {
02 namespace Storage {
03 type ContentObjectStorage = ArrayBuffer | ReadableStream | string | Uint8Array;
04 interface StorageInstance {
05 list(): Promise<{
06 entries: {
07 key: string;
08 content_length?: number;
09 }[];
10 }>;
11 put(key: string, value: ContentObjectStorage, options?: {
12 'content-length'?: string;
13 'content-type'?: string;
14 }): Promise<void>;
15 delete(key: string): Promise<void>;
16 get(key: string): Promise<StorageObject>;
17 }
18 interface StorageObject {
19 arrayBuffer(): Promise<ArrayBuffer>;
20 metadata: Map<string, string>;
21 contentType: string;
22 contentLength: number;
23 }
24 }
25 namespace Sql {
26 interface Connection {
27 query: (sql: string) => Promise<Rows>;
28 execute: (sql: string) => Promise<null>;
29 }
30 interface Rows {
31 next: () => Promise<Row>;
32 columnCount: () => number;
33 columnName: (index: number) => string;
34 columnType: (index: number) => string;
35 }
36 interface Row {
37 columnName: (index: number) => string;
38 columnType: (index: number) => string;
39 getValue: (index: number) => any;
40 getString: (index: number) => string;
41 }
42 interface Database {
43 connection: Connection;
44 open?: (name: string) => Promise<Connection>;
45 }
46 }
47}

Recursos relacionados

Azion Lib

As bibliotecas que a Azion Lib oferece e o pacote que contém cada uma.

Handlers

Os formatos de handler que o Azion Runtime chama e a requisição, o env e o ctx que um handler recebe.

API de metadados

As chaves de metadados que uma function com deploy feito lê da requisição, com o que cada uma contém.

Azion CLI dev

Sirva uma function localmente e teste um handler antes de fazer o deploy.