/ 
Unblock-HTTP2-0.10
/ Unblock::HTTP2::NativeABI

NAME

Unblock::HTTP2::NativeABI - Native transport ABI for Unblock::HTTP2

DESCRIPTION

This module exposes the optional native transport ABI used by XS-backed transports and event frameworks.

The ordinary input() and output() methods remain the portable interface. A native integration can instead feed borrowed input buffers directly and drain outbound nghttp2 buffers through a native sink callback.

The ABI works with both Unblock::HTTP2::Client and Unblock::HTTP2::Server.

DISCOVERY

my $definition = Unblock::HTTP2::NativeABI::definition();

The returned hash contains:

provider
abi_version
struct_size
operations_address

provider keeps the XS provider loaded and can be called again to obtain the current operations address.

Consumers must check both abi_version and struct_size before dereferencing operations.

HEADER

The installed header is:

Unblock/HTTP2/NativeABI/unblock_http2_native_abi.h

Its include directory is available through:

Unblock::HTTP2::NativeABI::native_include_dir()

The complete installed path is available through:

Unblock::HTTP2::NativeABI::header_path()

c_header() returns the same header text for build systems that prefer to generate a private copy.

C ABI

ABI version 1 begins with create, input, eof, and destroy. HTTP/2 then appends native output and readiness operations.

create receives one Unblock::HTTP2 Client or Server object and returns a connection-local native context. Keep that context for the lifetime of the HTTP/2 connection.

BORROWED INPUT

The native input operation receives:

const char *data
size_t length
size_t *consumed

data remains owned by the caller. Unblock::HTTP2 may inspect it only during the input call and never retains the pointer after the call returns.

libnghttp2 incrementally retains protocol parsing state, so fragmented HTTP/2 frames do not require the caller to preserve an incomplete prefix. A successful call normally reports the complete input window as consumed.

ABI version 1 uses these input result codes:

INPUT_OK       0
INPUT_MORE     1
INPUT_CLOSED   3

INPUT_MORE is reserved for compatibility with the common Unblock borrowed input pattern. The current HTTP/2 implementation does not normally return it.

NATIVE OUTPUT

output drains generated HTTP/2 bytes directly from libnghttp2 into a native sink callback.

The sink receives a borrowed buffer:

const char *data
size_t length

That pointer is valid only for the duration of the sink call. The sink must write or copy the bytes before returning.

The sink return value controls draining:

OUTPUT_CONTINUE   keep draining
OUTPUT_PAUSE      current chunk was accepted; stop after it
OUTPUT_ERROR      fatal sink failure

OUTPUT_PAUSE provides transport backpressure without losing the chunk that was just accepted. Call output again when the transport can accept more.

produced reports the number of bytes accepted by the sink during the call.

EOF

HTTP/2 has no message framing based on transport EOF. eof therefore closes the connection and returns INPUT_CLOSED.

FALLBACK

The native ABI is an optimization. A framework that does not use XS, cannot consume ABI version 1, or chooses not to use the fast path should continue to use input(), output(), want_read(), and want_write().