hpack.3

.\" $OpenBSD$
.\"
.\" Copyright (c) 2019 Reyk Floeter <reyk@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: May 23 2019 $
.Dt HPACK 3
.Os
.Sh NAME
.Nm hpack_init ,
.Nm hpack_table_new ,
.Nm hpack_table_free ,
.Nm hpack_table_size ,
.Nm hpack_decode ,
.Nm hpack_encode ,
.Nm hpack_header_new ,
.Nm hpack_header_add ,
.Nm hpack_header_free ,
.Nm hpack_headerblock_new ,
.Nm hpack_headerblock_free ,
.Nm hpack_huffman_decode ,
.Nm hpack_huffman_decode_str ,
.Nm hpack_huffman_encode
.Nd HPACK header compression for HTTP/2
.Sh SYNOPSIS
.In sys/queue.h
.In hpack.h
.Ft int
.Fn hpack_init void
.Ft struct hpack_table *
.Fn hpack_table_new "size_t max_table_size"
.Ft void
.Fn hpack_table_free "struct hpack_table *hpack"
.Ft size_t
.Fn hpack_table_size "struct hpack_table *hpack"
.Ft struct hpack_headerblock *
.Fn hpack_decode "unsigned char *data" "size_t len" "struct hpack_table *hpack"
.Ft unsigned char *
.Fn hpack_encode "struct hpack_headerblock *hdrs" "size_t *encoded_len" "struct hpack_table *hpack"
.Ft struct hpack_header *
.Fn hpack_header_new void
.Ft struct hpack_header *
.Fn hpack_header_add "struct hpack_headerblock *hdrs" "const char *key" "const char *value" "enum hpack_header_index index"
.Ft void
.Fn hpack_header_free "struct hpack_header *hdr"
.Ft struct hpack_headerblock *
.Fn hpack_headerblock_new void
.Ft void
.Fn hpack_headerblock_free "struct hpack_headerblock *hdrs"
.Ft unsigned char *
.Fn hpack_huffman_decode "unsigned char *data" "size_t len" "size_t *decoded_len"
.Ft char *
.Fn hpack_huffman_decode_str "unsigned char *data" "size_t len"
.Ft unsigned char *
.Fn hpack_huffman_encode "unsigned char *data" "size_t len" "size_t *encoded_len"
.Sh DESCRIPTION
The
.Nm hpack
family of functions provides an API to decode and encode HPACK header
compression for HTTP/2.
.Pp
The
.Vt hpack_header
and
.Vt hpack_headerblock
structures are defined as
.In sys/queue.h
tail queue element and head of the following types:
.Bd -literal
struct hpack_header {
	char				*hdr_name;
	char				*hdr_value;
	enum hpack_header_index		 hdr_index;
	TAILQ_ENTRY(hpack_header)	 hdr_entry;
};
TAILQ_HEAD(hpack_headerblock, hpack_header);
.Ed
.Pp
The
.Fa index
argument can be specified as one of the following values:
.Dv HPACK_INDEX ,
.Dv HPACK_NO_INDEX ,
or
.Dv HPACK_NEVER_INDEX
to add the header to the index of the dynamic HPACK table,
to exclude the header from the index,
or to exclude the header from the index and to mark it as sensitive to
never include it in the index.
.Sh RETURN VALUES
.Fn hpack_init
returns 0 on success or -1 on error.
.Pp
.Fn hpack_table_size
returns the current size of the dynamic HPACK table or 0 if it is empty.
.Pp
.Fn hpack_table_new ,
.Fn hpack_decode ,
.Fn hpack_encode ,
.Fn hpack_header_new ,
.Fn hpack_header_add ,
.Fn hpack_headerblock_new ,
.Fn hpack_huffman_decode ,
.Fn hpack_huffman_decode_str ,
and
.Fn hpack_huffman_encode
return
.Dv NULL
on error or an out-of-memory condition.
.Sh SEE ALSO
.Xr queue 3 ,
.Xr relayd 8
.Sh STANDARDS
.Rs
.%A R. Peon
.%A H. Ruellan
.%D May 2015
.%R RFC 7541
.%T HPACK: Header Compression for HTTP/2
.Re
.Sh HISTORY
The
.Nm hpack
API first appeared on
.Lk https://github.com/reyk/hpack .
.Sh AUTHORS
.An Reyk Floeter Aq Mt reyk@openbsd.org