Request Context

The context parameter passed to handleRequest(context) in HTTP ingress handlers wraps the incoming HTTP request. It provides access to parameters, headers, body, and request metadata.

Quick Example

export function handleRequest(context) {
  const name = context.getParameter("name");
  const body = JSON.parse(context.getBody());
  const auth = context.getHeader("Authorization");

  return Results.json().renderRaw(JSON.stringify({ received: true }));
}

Methods

Parameters

context.getParameter(name)

Get a single query or form parameter by name.

• Parameters: name: string
• Returns: string | null

// URL: /api/items?page=2&limit=10
const page = context.getParameter("page");   // "2"
const limit = context.getParameter("limit"); // "10"

context.getParameterAsInteger(name)

Get a parameter parsed as an integer. Returns null if the parameter is missing or not a valid integer.

• Parameters: name: string
• Returns: number | null

const page = context.getParameterAsInteger("page"); // 2
const bad = context.getParameterAsInteger("invalid"); // null

context.getParameterMap()

Get all parameters as a map. Each key maps to an array of values (since a parameter can appear multiple times).

• Returns: Map<string, string[]>

const params = context.getParameterMap();
// { "page": ["2"], "tags": ["js", "web"] }

Body

context.getBody()

Read the full request body as a string.

• Returns: string

// POST with JSON body
const body = JSON.parse(context.getBody());
const { name, email } = body;

context.getContentType()

Get the request's Content-Type header value.

• Returns: string

if (context.getContentType() === "application/json") {
  const data = JSON.parse(context.getBody());
}

Headers

context.getHeader(name)

Get a single header value by name.

• Parameters: name: string
• Returns: string | null

const token = context.getHeader("Authorization");
const userAgent = context.getHeader("User-Agent");

context.getHeaders()

Get all headers as a map.

• Returns: Map<string, string>

const headers = context.getHeaders();

Request Metadata

context.getRequestPath()

Get the request URI path.

• Returns: string

const path = context.getRequestPath();
// → "/backend/api/items"

context.getMethod()

Get the HTTP method (GET, POST, DELETE, etc.).

• Returns: string

const method = context.getMethod();
// → "POST"

context.getRemoteAddr()

Get the client's IP address.

• Returns: string

const ip = context.getRemoteAddr();
console.log("Request from:", ip);

File Uploads

context.getFileItemIterator()

Get an iterator for multipart file uploads. Use this for processing uploaded files.

• Returns: FileItemIterator

const iterator = context.getFileItemIterator();
while (iterator.hasNext()) {
  const item = iterator.next();
  const name = item.getFieldName();
  const stream = item.openStream();
  // process the uploaded file...
}

Request-Scoped Data

context.setAttribute(key, value)

Store data scoped to the current request. Useful for passing data between middleware-like functions.

• Parameters: key: string, value: any

context.getAttribute(key)

Retrieve request-scoped data.

• Parameters: key: string
• Returns: any

context.setAttribute("userId", authenticatedUser.id);
// later...
const userId = context.getAttribute("userId");

Raw Servlet Access

context.getServletRequest()

Access the underlying HttpServletRequest object for advanced use cases.

• Returns: HttpServletRequest

WARNING

Only use this when the higher-level methods don't cover your use case. Direct servlet access bypasses the convenience layer.

Common Patterns

JSON POST Handler

export function handleRequest(context) {
  const body = JSON.parse(context.getBody());

  if (!body.name || !body.email) {
    return Results.badRequest().json().renderRaw(
      JSON.stringify({ error: "name and email are required" })
    );
  }

  const id = UserService.createUser(body);
  return Results.created("/api/users/" + id)
    .json()
    .renderRaw(JSON.stringify({ id }));
}

Paginated GET Handler

export function handleRequest(context) {
  const page = context.getParameterAsInteger("page") || 1;
  const limit = context.getParameterAsInteger("limit") || 20;
  const search = context.getParameter("q") || "";

  const items = ItemService.findItems(search, page, limit);
  const total = ItemService.countItems(search);

  return Results.json().renderRaw(JSON.stringify({
    data: items,
    page,
    limit,
    total
  }));
}

Auth Header Extraction

export function handleRequest(context) {
  const auth = context.getHeader("Authorization");
  if (!auth || !auth.startsWith("Bearer ")) {
    return Results.unauthorized().json().renderRaw(
      JSON.stringify({ error: "Missing or invalid Authorization header" })
    );
  }
  const token = auth.substring(7);
  // validate token...
}