Hcs.Response

hcs · API reference

HTTP response type and constructors.

Use this module to create text, HTML, JSON, redirect, error, streaming, bigstring, cstruct, file, and prebuilt responses. The returned Response.t is the canonical value consumed by the server engine.

HTTP responses returned by HCS handlers.

Handlers return t. Most code uses the convenience constructors:

let index _req = Hcs.Response.html "<h1>Hello</h1>"
let api _req = Hcs.Response.json {|{"ok":true}|}
let redirect _req = Hcs.Response.see_other "/login"

For long-lived responses, use stream directly or higher-level helpers such as Sse.

module Prebuilt : sig ... end
type body = 
  | Empty
  | String of string
  | Cstruct of Cstruct.t
  | Bigstring of Bigstringaf.t
  | Stream of {
    content_length : int64 option;
    flush_headers_immediately : bool;
    next : unit -> Cstruct.t option;
  }
  | Prebuilt_body of Prebuilt.t (* Response body representation consumed by the server engine. *)
type t = {
  status : Status.t;
  headers : (string * string) list;
  body : body;
}

Complete HTTP response.

val make : ?status:Status.t -> ?headers:(string * string) list -> string -> t

Build a string response. Defaults to ``OK`.

val empty : ?status:Status.t -> ?headers:(string * string) list -> unit -> t

Build a response with no body. Defaults to ``No_content`.

val ok : ?headers:(string * string) list -> string -> t
val created : 
  ?headers:(string * string) list ->
  ?location:string ->
  string ->
  t
val accepted : ?headers:(string * string) list -> string -> t
val no_content : ?headers:(string * string) list -> unit -> t
val redirect : 
  ?permanent:bool ->
  ?headers:(string * string) list ->
  string ->
  t
val moved_permanently : ?headers:(string * string) list -> string -> t
val found : ?headers:(string * string) list -> string -> t
val see_other : ?headers:(string * string) list -> string -> t
val temporary_redirect : ?headers:(string * string) list -> string -> t
val not_modified : ?headers:(string * string) list -> unit -> t
val bad_request : ?headers:(string * string) list -> ?body:string -> unit -> t
val unauthorized : 
  ?headers:(string * string) list ->
  ?www_authenticate:string ->
  unit ->
  t
val forbidden : ?headers:(string * string) list -> ?body:string -> unit -> t
val not_found : ?headers:(string * string) list -> ?body:string -> unit -> t
val method_not_allowed : 
  ?headers:(string * string) list ->
  allowed:Method.t list ->
  unit ->
  t
val conflict : ?headers:(string * string) list -> ?body:string -> unit -> t
val gone : ?headers:(string * string) list -> ?body:string -> unit -> t
val unprocessable_entity : 
  ?headers:(string * string) list ->
  ?body:string ->
  unit ->
  t
val too_many_requests : 
  ?headers:(string * string) list ->
  ?retry_after:int ->
  unit ->
  t
val internal_error : 
  ?headers:(string * string) list ->
  ?body:string ->
  unit ->
  t
val not_implemented : 
  ?headers:(string * string) list ->
  ?body:string ->
  unit ->
  t
val bad_gateway : ?headers:(string * string) list -> ?body:string -> unit -> t
val service_unavailable : 
  ?headers:(string * string) list ->
  ?retry_after:int ->
  unit ->
  t
val gateway_timeout : 
  ?headers:(string * string) list ->
  ?body:string ->
  unit ->
  t

Status-specific constructors.

val text : ?status:Status.t -> string -> t

Plain-text UTF-8 response.

val html : ?status:Status.t -> string -> t

HTML UTF-8 response.

val json : ?status:Status.t -> string -> t

JSON response. The body is assumed to already be valid JSON.

val xml : ?status:Status.t -> string -> t

XML response.

val stream : 
  ?status:Status.t ->
  ?headers:(string * string) list ->
  ?flush_headers_immediately:bool ->
  ?content_length:int64 ->
  (unit -> Cstruct.t option) ->
  t

Streaming response. next returns chunks until None.

val bigstring : 
  ?status:Status.t ->
  ?headers:(string * string) list ->
  Bigstringaf.t ->
  t
val cstruct : 
  ?status:Status.t ->
  ?headers:(string * string) list ->
  Cstruct.t ->
  t
val prebuilt : Prebuilt.t -> t

Binary/prebuilt response constructors.

val with_header : string -> string -> t -> t
val with_headers : (string * string) list -> t -> t
val with_body : string -> t -> t
val with_body_raw : body -> t -> t
val with_status : Status.t -> t -> t
val with_content_type : string -> t -> t
val with_cache_control : string -> t -> t
val with_no_cache : t -> t
val with_cors : ?origin:string -> ?methods:string -> ?headers:string -> t -> t

Response modifiers.

Add a Set-Cookie header.

Expire a cookie by setting Max-Age=0.