# Interface HttpResponse

An HttpResponse is valid until either onAborted callback or any of the .end/.tryEnd calls succeed. You may attach user data to this object.

interface HttpResponse {
close(): HttpResponse;
collectBody(
maxSize: number,
handler: (fullBody: ArrayBuffer) => void,
): HttpResponse;
cork(cb: () => void): HttpResponse;
end(body?: RecognizedString, closeConnection?: boolean): HttpResponse;
endWithoutBody(
reportedContentLength?: number,
closeConnection?: boolean,
): HttpResponse;
getProxiedRemoteAddress(): ArrayBuffer;
getProxiedRemoteAddressAsText(): ArrayBuffer;
getProxiedRemotePort(): number;
getRemoteAddress(): ArrayBuffer;
getRemoteAddressAsText(): ArrayBuffer;
getRemotePort(): number;
getWriteOffset(): number;
onAborted(handler: () => void): HttpResponse;
onData(
handler: (chunk: ArrayBuffer, isLast: boolean) => void,
): HttpResponse;
onDataV2(
handler: (chunk: ArrayBuffer, maxRemainingBodyLength: bigint) => void,
): HttpResponse;
onWritable(handler: (offset: number) => boolean): HttpResponse;
pause(): void;
resume(): void;
tryEnd(
fullBodyOrChunk: RecognizedString,
totalSize: number,
): [boolean, boolean];
upgrade<UserData>(
userData: UserData,
secWebSocketKey: RecognizedString,
secWebSocketProtocol: RecognizedString,
secWebSocketExtensions: RecognizedString,
context: us_socket_context_t,
): void;
write(chunk: RecognizedString): boolean;
writeHeader(key: RecognizedString, value: RecognizedString): HttpResponse;
writeStatus(status: RecognizedString): HttpResponse;
[key: string]: any;
}

#### Indexable

- [key: string]: any

  Arbitrary user data may be attached to this object

- Defined in index.d.ts:138

##### Index

### Methods

close
collectBody
cork
end
endWithoutBody
getProxiedRemoteAddress
getProxiedRemoteAddressAsText
getProxiedRemotePort
getRemoteAddress
getRemoteAddressAsText
getRemotePort
getWriteOffset
onAborted
onData
onDataV2
onWritable
pause
resume
tryEnd
upgrade
write
writeHeader
writeStatus

## Methods

### close

- close(): HttpResponse

  Immediately force closes the connection. Any onAborted callback will run.

  #### Returns HttpResponse

  - Defined in index.d.ts:168

### collectBody

- collectBody(
  maxSize: number,
  handler: (fullBody: ArrayBuffer) => void,
  ): HttpResponse

  Accumulates all data chunks and calls handler with the complete body as an ArrayBuffer once all data has arrived. If the total body size exceeds maxSize bytes, handler is called with null instead.

  #### Parameters

  - maxSize: number
  - handler: (fullBody: ArrayBuffer) => void

  #### Returns HttpResponse

  - Defined in index.d.ts:199

### cork

- cork(cb: () => void): HttpResponse

  Corking a response is a performance improvement in both CPU and network, as you ready the IO system for writing multiple chunks at once. By default, you're corked in the immediately executing top portion of the route handler. In all other cases, such as when returning from await, or when being called back from an async database request or anything that isn't directly executing in the route handler, you'll want to cork before calling writeStatus, writeHeader or just write. Corking takes a callback in which you execute the writeHeader, writeStatus and such calls, in one atomic IO operation. This is important, not only for TCP but definitely for TLS where each write would otherwise result in one TLS block being sent off, each with one send syscall.

  Example usage:

      res.cork(() => {
        res.writeStatus("200 OK").writeHeader("Some", "Value").write("Hello world!");
      });

  #### Parameters

  - cb: () => void

  #### Returns HttpResponse

  - Defined in index.d.ts:242

### end

- end(body?: RecognizedString, closeConnection?: boolean): HttpResponse

  Ends this response by copying the contents of body.

  #### Parameters

  - `Optional` body: RecognizedString
  - `Optional` closeConnection: boolean

  #### Returns HttpResponse

  - Defined in index.d.ts:161

### endWithoutBody

- endWithoutBody(
  reportedContentLength?: number,
  closeConnection?: boolean,
  ): HttpResponse

  Ends this response without a body.

  #### Parameters

  - `Optional` reportedContentLength: number
  - `Optional` closeConnection: boolean

  #### Returns HttpResponse

  - Defined in index.d.ts:163

### getProxiedRemoteAddress

- getProxiedRemoteAddress(): ArrayBuffer

  Returns the remote IP address in binary format (4 or 16 bytes), as reported by the PROXY Protocol v2 compatible proxy.

  #### Returns ArrayBuffer

  - Defined in index.d.ts:219

### getProxiedRemoteAddressAsText

- getProxiedRemoteAddressAsText(): ArrayBuffer

  Returns the remote IP address as text, as reported by the PROXY Protocol v2 compatible proxy.

  #### Returns ArrayBuffer

  - Defined in index.d.ts:222

### getProxiedRemotePort

- getProxiedRemotePort(): number

  Returns the remote port number, as reported by the PROXY Protocol v2 compatible proxy.

  #### Returns number

  - Defined in index.d.ts:225

### getRemoteAddress

- getRemoteAddress(): ArrayBuffer

  Returns the remote IP address in binary format (4 or 16 bytes).

  #### Returns ArrayBuffer

  - Defined in index.d.ts:210

### getRemoteAddressAsText

- getRemoteAddressAsText(): ArrayBuffer

  Returns the remote IP address as text.

  #### Returns ArrayBuffer

  - Defined in index.d.ts:213

### getRemotePort

- getRemotePort(): number

  Returns the remote port number.

  #### Returns number

  - Defined in index.d.ts:216

### getWriteOffset

- getWriteOffset(): number

  Returns the global byte write offset for this response. Use with onWritable.

  #### Returns number

  - Defined in index.d.ts:171

### onAborted

- onAborted(handler: () => void): HttpResponse

  Every HttpResponse MUST have an attached abort handler IF you do not respond to it immediately inside of the callback. Returning from an Http request handler without attaching (by calling onAborted) an abort handler is ill-use and will terminate. When this event emits, the response has been aborted and may not be used.

  #### Parameters

  - handler: () => void

  #### Returns HttpResponse

  - Defined in index.d.ts:183

### onData

- onData(handler: (chunk: ArrayBuffer, isLast: boolean) => void): HttpResponse

  Handler for reading HTTP request body data. Must be attached before performing any asynchronous operation, otherwise data may be lost. You MUST copy the data of chunk if isLast is not true. We Neuter ArrayBuffers on return, making them zero length.

  #### Parameters

  - handler: (chunk: ArrayBuffer, isLast: boolean) => void

  #### Returns HttpResponse

  - Defined in index.d.ts:188

### onDataV2

- onDataV2(
  handler: (chunk: ArrayBuffer, maxRemainingBodyLength: bigint) => void,
  ): HttpResponse

  Handler for reading HTTP request body data. V2. Must be attached before performing any asynchronous operation, otherwise data may be lost. You MUST copy the data of chunk if maxRemainingBodyLength is not 0. We Neuter ArrayBuffers on return, making them zero length.

  maxRemainingBodyLength is the known maximum of the remaining body length. Can be used to preallocate a receive buffer.

  #### Parameters

  - handler: (chunk: ArrayBuffer, maxRemainingBodyLength: bigint) => void

  #### Returns HttpResponse

  - Defined in index.d.ts:207

### onWritable

- onWritable(handler: (offset: number) => boolean): HttpResponse

  Registers a handler for writable events. Continue failed write attempts in here. You MUST return true for success, false for failure. Writing nothing is always success, so by default you must return true.

  #### Parameters

  - handler: (offset: number) => boolean

  #### Returns HttpResponse

  - Defined in index.d.ts:177

### pause

- pause(): void

  Pause HTTP request body streaming (throttle). Some buffered data may still be sent to onData.

  #### Returns void

  - Defined in index.d.ts:192

### resume

- resume(): void

  Resume HTTP request body streaming (unthrottle).

  #### Returns void

  - Defined in index.d.ts:195

### tryEnd

- tryEnd(fullBodyOrChunk: RecognizedString, totalSize: number): [boolean, boolean]

  Ends this response, or tries to, by streaming appropriately sized chunks of body. Use in conjunction with onWritable. Returns tuple [ok, hasResponded].

  #### Parameters

  - fullBodyOrChunk: RecognizedString
  - totalSize: number

  #### Returns [boolean, boolean]

  - Defined in index.d.ts:165

### upgrade

- upgrade<UserData>(
  userData: UserData,
  secWebSocketKey: RecognizedString,
  secWebSocketProtocol: RecognizedString,
  secWebSocketExtensions: RecognizedString,
  context: us_socket_context_t,
  ): void

  Upgrades a HttpResponse to a WebSocket. See UpgradeAsync, UpgradeSync example files.

  #### Type Parameters

  - UserData

  #### Parameters

  - userData: UserData
  - secWebSocketKey: RecognizedString
  - secWebSocketProtocol: RecognizedString
  - secWebSocketExtensions: RecognizedString
  - context: us_socket_context_t

  #### Returns void

  - Defined in index.d.ts:245

### write

- write(chunk: RecognizedString): boolean

  Enters or continues chunked encoding mode. Writes part of the response. End with zero length write. Returns true if no backpressure was added.

  #### Parameters

  - chunk: RecognizedString

  #### Returns boolean

  - Defined in index.d.ts:159

### writeHeader

- writeHeader(key: RecognizedString, value: RecognizedString): HttpResponse

  Writes key and value to HTTP response. See writeStatus and corking.

  #### Parameters

  - key: RecognizedString
  - value: RecognizedString

  #### Returns HttpResponse

  - Defined in index.d.ts:157

### writeStatus

- writeStatus(status: RecognizedString): HttpResponse

  Writes the HTTP status message such as "200 OK". This has to be called first in any response, otherwise it will be called automatically with "200 OK".

  If you want to send custom headers in a WebSocket upgrade response, you have to call writeStatus with "101 Switching Protocols" before you call writeHeader, otherwise your first call to writeHeader will call writeStatus with "200 OK" and the upgrade will fail.

  As you can imagine, we format outgoing responses in a linear buffer, not in a hash table. You can read about this in the user manual under "corking".

  #### Parameters

  - status: RecognizedString

  #### Returns HttpResponse

  - Defined in index.d.ts:153