Types

Azion Lib types of the @aziontech/types package for function handlers, the request and its metadata, and the handler context.

Last updated

View as Markdown Agent setup

The @aziontech/types package is the Azion Lib library of TypeScript types for code that runs on Azion Runtime. It declares the handler shapes of a function, the request with its metadata, and the context a handler receives. The package holds types only: its JavaScript module exports nothing and makes no API call, so you import every name with import type.

Install the package:

npm install @aziontech/types

The TypeScript samples on this page import their types with import type. The metadata sample runs in Node.js, and the handler samples run inside a function served locally with azion dev.

Under azion dev, request.metadata is absent, so the handler samples on this page read it with optional chaining (metadata?.). Locally, a module firewall handler receives a ctx that holds only waitUntil. For the metadata a deployed function reads, refer to Metadata API.

AzionRuntimeRequestMetadata

The metadata object that AzionRuntimeRequest carries in metadata. The interface declares 26 keys, every one a required string, plus a string index signature that types any other key.

PropertyTypeRequiredDescription
geoip_asnstringYesAutonomous system number.
geoip_citystringYesCity code.
geoip_city_continent_codestringYesContinent code of the city.
geoip_city_country_codestringYesCountry code of the city.
geoip_city_country_namestringYesCountry name of the city.
geoip_continent_codestringYesContinent code.
geoip_country_codestringYesCountry code.
geoip_country_namestringYesCountry name.
geoip_regionstringYesRegion code.
geoip_region_namestringYesRegion name.
remote_addrstringYesIP address of the client.
remote_portstringYesTCP port of the client.
remote_userstringYesUser given in the URL.
server_protocolstringYesProtocol of the request.
server_fingerprintstringYesServer TLS fingerprint.
server_fingerprint_ja4hstringYesServer JA4H fingerprint.
ssl_cipherstringYesTLS cipher of the session.
ssl_protocolstringYesTLS protocol of the session.
client_fingerprintstringYesClient fingerprint.
client_idstringYesIdentifier of the Azion account that owns the workload.
configuration_idstringYesIdentifier of the workload that received the request.
edge_connector_idstringYes—
function_idstringYesIdentifier of the function that runs for the request.
http_ssl_ja4stringYesJA4 TLS fingerprint of the request.
request_idstringYesUnique ID of the request.
solution_idstringYesInternal identifier of the solution that handles the request.
[key: string]stringNoAny other key of the object.

An object literal typed as AzionRuntimeRequestMetadata must carry all 26 keys, or tsc stops with error TS2740 and names the missing ones. To type an object that holds some of the keys, wrap the interface in Partial.

This sample builds a metadata object with 16 of the keys:

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');

Output:

16 fields

AzionRuntimeRequest

The request a module handler receives: the standard Request with a metadata property.

TypeScript
01type AzionRuntimeRequest = Request & {
02 metadata: AzionRuntimeRequestMetadata;
03};
PropertyTypeRequiredDescription
metadataAzionRuntimeRequestMetadataYesThe metadata of the request.

AzionRuntimeModule

The default export of a function in the module form: an object with a fetch handler, a firewall handler, or both. The module form is the handler shape Handlers recommends.

TypeScript
01interface AzionRuntimeModule {
02 fetch?: (request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>;
03 firewall?: (request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>;
04}
PropertyTypeRequiredDescription
fetch(request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>NoThe handler Azion Runtime calls for a request.
firewall(request: AzionRuntimeRequest, env?: null, ctx?: AzionRuntimeCtx) => Promise<Response>NoThe firewall handler, as the type declares it.

This function checks its default export against the type with satisfies, and responds with the city of the client:

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;

Served locally with azion dev, where the request carries no metadata, a request returns:

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

The function logs:

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

AzionRuntimeCtx

The context that AzionRuntimeModule declares as the third argument of both handlers.

TypeScript
01interface AzionRuntimeCtx {
02 waitUntil: (promise: Promise<unknown>) => void;
03 args?: Record<string, unknown>;
04}
PropertyTypeRequiredDescription
waitUntil(promise: Promise<unknown>) => voidYesExtends the execution until promise settles.
argsRecord<string, unknown>NoThe args of the function instance.

AzionFetchEvent

The event a listener registered with addEventListener for the fetch type receives. It extends the standard Event.

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}
PropertyTypeRequiredDescription
requestRequest & { metadata: AzionRuntimeRequestMetadata }YesThe request, with its metadata.
waitUntil(promise: Promise<unknown>) => voidYesDeclared by the type.
respondWith(response: Response | Promise<Response>) => voidYesSets the response the function sends to the client.

In a JavaScript function, a JSDoc comment applies the type to the event. This listener responds with the city of the client:

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});

Served locally with azion dev, the listener returns the same response as the AzionRuntimeModule sample and logs the same three lines:

Text
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

The type of a listener for the fetch event.

type FetchEventListener = (event: AzionFetchEvent, args?: Record<string, unknown>) => void | Promise<void>;
ParameterTypeRequiredDescription
eventAzionFetchEventYesThe fetch event.
argsRecord<string, unknown>NoThe args the listener receives.

AzionFirewallEvent

The event type the package declares for a firewall listener. It extends AzionFetchEvent with three methods.

TypeScript
01interface AzionFirewallEvent extends AzionFetchEvent {
02 deny: () => void;
03 drop: () => void;
04 continue: () => void;
05}
PropertyTypeRequiredDescription
deny() => voidYesDeclared by the type.
drop() => voidYesDeclared by the type.
continue() => voidYesDeclared by the type.
request, waitUntil, respondWithas in AzionFetchEventYesInherited from AzionFetchEvent.

AzionRuntimeFirewallCtx

The context type the package declares for firewall modules. It extends AzionRuntimeCtx with three methods. AzionRuntimeModule types the ctx of its firewall handler as AzionRuntimeCtx, not as this type.

TypeScript
01interface AzionRuntimeFirewallCtx extends AzionRuntimeCtx {
02 deny: () => void;
03 continue: () => void;
04 drop: () => void;
05}
PropertyTypeRequiredDescription
deny() => voidYesDeclared by the type.
continue() => voidYesDeclared by the type.
drop() => voidYesDeclared by the type.
waitUntil(promise: Promise<unknown>) => voidYesInherited from AzionRuntimeCtx.
argsRecord<string, unknown>NoInherited from AzionRuntimeCtx.

FirewallEventListener

The type of a listener for the firewall event.

type FirewallEventListener = (event: AzionFirewallEvent, args?: Record<string, unknown>) => void | Promise<void>;
ParameterTypeRequiredDescription
eventAzionFirewallEventYesThe firewall event.
argsRecord<string, unknown>NoThe args the listener receives.

Azion namespace

The package also exports the Azion namespace, which declares the Azion.Storage and Azion.Sql namespaces. For the runtime APIs these names describe, refer to Object Storage API and 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}
Azion Lib

The libraries Azion Lib ships and the package that carries each one.

Handlers

The handler shapes Azion Runtime calls, and the request, env, and ctx a handler receives.

Metadata API

The metadata keys a deployed function reads from the request, with what each one holds.

Azion CLI dev

Serve a function locally and test a handler before you deploy it.