response.h File Reference

#include <keel/allocator.h>
#include <keel/drain.h>
#include <stddef.h>
#include <sys/types.h>

Include dependency graph for response.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KlResponse

Typedefs
typedef struct KlTls	KlTls
typedef int(*	KlWriteFn) (void *ctx, const char *data, size_t len)
	Pluggable write callback — same signature as sh_json's ShJsonWriteFn.
typedef struct KlResponse	KlResponse

Enumerations
enum	KlBodyMode { KL_BODY_NONE , KL_BODY_BUFFER , KL_BODY_FILE , KL_BODY_STREAM }

Functions
int	kl_response_init (KlResponse *res, KlAllocator *alloc)
	Initialize a response, allocating the header buffer.
void	kl_response_reset (KlResponse *res)
	Fast reinit for keep-alive — reuses header buffer, no alloc.
void	kl_response_status (KlResponse *res, int code)
	Set the HTTP status code (default 200).
int	kl_response_header (KlResponse *res, const char *name, const char *value)
	Append a header. Both name and value must be null-terminated. Strings containing CR or LF are rejected (header injection guard).
void	kl_response_body_borrow (KlResponse *res, const char *data, size_t len)
	Set a buffered body (pointer is borrowed, not copied).
int	kl_response_body_copy (KlResponse *res, const char *data, size_t len)
	Set a buffered body by copying data into an owned buffer.
void	kl_response_file (KlResponse *res, int fd, off_t size)
	Set a file body for zero-copy sendfile transfer.
void	kl_response_free (KlResponse *res)
	Free response resources (header buffer, close file fd).
int	kl_response_json (KlResponse *res, int code, const char *json, size_t len)
	Convenience: set status, Content-Type: application/json, and body.
int	kl_response_error (KlResponse *res, int code, const char *message)
	Convenience: set status, Content-Type: text/plain, and error message.
int	kl_response_enable_drain (KlResponse *res, KlAllocator *alloc, size_t max_size)
	Enable drain-based backpressure for chunked streaming.
int	kl_response_begin_stream (KlResponse *res, int status, KlWriteFn *out_write, void **out_ctx)
	Begin chunked streaming response.
int	kl_response_end_stream (KlResponse *res)
	End chunked stream (sends final zero-length chunk).
int	kl_response_send (KlResponse *res)
	Flush headers + body to the connection fd.

Typedef Documentation

KlTls

typedef struct KlTls KlTls

KlWriteFn

typedef int(* KlWriteFn) (void *ctx, const char *data, size_t len)

Pluggable write callback — same signature as sh_json's ShJsonWriteFn.

KlResponse

typedef struct KlResponse KlResponse

Enumeration Type Documentation

KlBodyMode

enum KlBodyMode

Enumerator
KL_BODY_NONE	No body
KL_BODY_BUFFER	Buffered body
KL_BODY_FILE	File body (sendfile)
KL_BODY_STREAM	Chunked streaming body

Function Documentation

kl_response_init()

int kl_response_init	(	KlResponse *	res,
		KlAllocator *	alloc
	)

Initialize a response, allocating the header buffer.

Parameters

res	Response to initialize.
alloc	Allocator for header buffer growth.

Returns

0 on success, -1 on allocation failure.

kl_response_reset()

void kl_response_reset

(

KlResponse *

res

)

Fast reinit for keep-alive — reuses header buffer, no alloc.

kl_response_status()

void kl_response_status	(	KlResponse *	res,
		int	code
	)

Set the HTTP status code (default 200).

kl_response_header()

int kl_response_header	(	KlResponse *	res,
		const char *	name,
		const char *	value
	)

Append a header. Both name and value must be null-terminated. Strings containing CR or LF are rejected (header injection guard).

Returns

0 on success, -1 on failure (CRLF injection, NULL args, alloc failure).

kl_response_body_borrow()

void kl_response_body_borrow	(	KlResponse *	res,
		const char *	data,
		size_t	len
	)

Set a buffered body (pointer is borrowed, not copied).

Parameters

res	Response.
data	Body bytes (must remain valid until send completes).
len	Length in bytes.

kl_response_body_copy()

int kl_response_body_copy	(	KlResponse *	res,
		const char *	data,
		size_t	len
	)

Set a buffered body by copying data into an owned buffer.

Unlike kl_response_body_borrow(), the data is copied into a response-owned allocation that is freed by kl_response_reset() / kl_response_free(). Safe when the source may be freed before the response is sent.

Parameters

res	Response.
data	Body bytes (copied).
len	Length in bytes.

Returns

0 on success, -1 on allocation failure.

kl_response_file()

void kl_response_file	(	KlResponse *	res,
		int	fd,
		off_t	size
	)

Set a file body for zero-copy sendfile transfer.

Parameters

res	Response.
fd	Open file descriptor (ownership transferred to response).
size	File size in bytes.

kl_response_free()

void kl_response_free

(

KlResponse *

res

)

Free response resources (header buffer, close file fd).

kl_response_json()

int kl_response_json	(	KlResponse *	res,
		int	code,
		const char *	json,
		size_t	len
	)

Convenience: set status, Content-Type: application/json, and body.

kl_response_error()

int kl_response_error	(	KlResponse *	res,
		int	code,
		const char *	message
	)

Convenience: set status, Content-Type: text/plain, and error message.

Returns

0 on success, -1 on header append failure.

kl_response_enable_drain()

int kl_response_enable_drain	(	KlResponse *	res,
		KlAllocator *	alloc,
		size_t	max_size
	)

Enable drain-based backpressure for chunked streaming.

Must be called before kl_response_begin_stream(). When enabled, kl_stream_write() buffers data on would-block instead of spin-looping.

Parameters

res	Response.
alloc	Allocator for drain buffer.
max_size	Hard cap on buffered bytes (0 = unlimited).

Returns

0 on success, -1 on error.

kl_response_begin_stream()

int kl_response_begin_stream	(	KlResponse *	res,
		int	status,
		KlWriteFn *	out_write,
		void **	out_ctx
	)

Begin chunked streaming response.

Parameters

res	Response.
status	HTTP status code.
out_write	Receives the write callback function.
out_ctx	Receives the write callback context.

Returns

0 on success, -1 on write error.

kl_response_end_stream()

int kl_response_end_stream

(

KlResponse *

res

)

End chunked stream (sends final zero-length chunk).

Returns

0 on success, -1 on error.

kl_response_send()

int kl_response_send

(

KlResponse *

res

)

Flush headers + body to the connection fd.

Returns

0 when done, positive if more to send, -1 on error.