NAME

Protocol::HAP::HTTP - the HTTP/1.1 subset codec of HAP

SYNOPSIS

use Protocol::HAP::HTTP;

# Server side
my $length  = Protocol::HAP::HTTP::message_complete($buffer);
my $request = Protocol::HAP::HTTP::parse_request($message);
my $bytes   = Protocol::HAP::HTTP::build_response(
    status  => 200,
    headers => { 'Content-Type' => 'application/hap+json' },
    body    => $json,
);

# Client side
my $bytes    = Protocol::HAP::HTTP::build_request(
    method => 'GET',
    path   => '/accessories',
);
my $response = Protocol::HAP::HTTP::parse_response($message);

# Notifications
my $event = Protocol::HAP::HTTP::build_event($json);

DESCRIPTION

This module is one HTTP/1.1 codec for both ends of a connection: a server parses requests and builds responses, a client does the reverse, and neither can drift from the other. It is functions over strings. It opens no socket, holds no connection state, and never logs.

message_complete is the framing. A stream socket gives a reader whatever arrived, which is not a message: a request can span two reads, and two requests can share one. The caller keeps a buffer and asks this function how much of it is a message. It returns the length of the message, 0 when more bytes are necessary, and undef when the message is over the limit; a caller that gets undef closes the connection.

build_event builds the EVENT/1.0 notification message of HAP. The message looks like a response, but its protocol name is EVENT, so a controller can tell an unsolicited notification from the answer to a request it sent.

A status code that belongs to one application, and the header defaults that one application wants, are arguments: the codec knows RFC 9110, not HAP policy.

SEE ALSO

Protocol::HAP, Protocol::HAP::Server, spec/HAP-HTTP.md