HTTP

HTTP core types for Zig inspired by Rust http.

⚠️ I'm currently renovating an old house which does not allow me to work on requestz, h11 and http as much as I would like to. Further development will likely to start again around december 2022. In the meantime, feel free to fork :)

Installation

http is available on astrolabe.pm via gyro

gyro add ducdetronquito/http

Usage

Create an HTTP request

const Request = @import("http").Request;
const std = @import("std");

var request = try Request.builder(std.testing.allocator)
    .get("https://ziglang.org/")
    .header("GOTTA-GO", "FAST")
    .body("");
defer request.deinit();

Create an HTTP response

const Response = @import("http").Request;
const StatusCode = @import("http").StatusCode;
const std = @import("std");

var response = try Response.builder(std.testing.allocator)
    .status(.Ok)
    .header("GOTTA-GO", "FAST")
    .body("");
defer response.deinit();

API Reference

Structures

Headers

An HTTP header list

// The default constructor
fn init(allocator: *Allocator) Headers

// Add a header name and value
fn append(self: *Headers, name: []const u8, value: []const u8) !void

// Retrieve the first matching header
fn get(self: Headers, name: []const u8) ?Header

// Retrieve a list of matching headers
fn list(self: Headers, name: []const u8) ![]Header

// Retrieve the number of headers
fn len(self: Headers) usize

// Retrieve all headers
fn items(self: Headers) []Header

Header issues are tracked here: #2

Request

An HTTP request object produced by the request builder.

const Request = struct {
    method: Method,
    uri: Uri,
    version: Version,
    headers: Headers,
    body: []const u8,
};

// The default constructor to start building a request
fn builder(allocator: *Allocator) RequestBuilder

// Release the memory allocated by the headers
fn deinit(self: *Request) void

RequestBuilder

The request builder.

// The default constructor
default(allocator: *Allocator) RequestBuilder

// Set the request's payload.
// This function returns the final request objet or a potential error
// collected during the build steps
fn body(self: *RequestBuilder, value: []const u8) RequestError!Request

// Shortcut to define a CONNECT request to the provided URI
fn connect(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define a DELETE request to the provided URI
fn delete(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define a GET request to the provided URI
fn get(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define an HEAD request to the provided URI
fn head(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Set a request header name and value
fn header(self: *RequestBuilder, name: []const u8, value: []const u8) *RequestBuilder

// Set the request's method
fn method(self: *RequestBuilder, value: Method) *RequestBuilder

// Shortcut to define an OPTIONS request to the provided URI
fn options(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define a PATCH request to the provided URI
fn patch(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define a POST request to the provided URI
fn post(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define a PUT request to the provided URI
fn put(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Shortcut to define a TRACE request to the provided URI
fn trace(self: *RequestBuilder, _uri: []const u8) *RequestBuilder

// Set the request's URI
fn uri(self: *RequestBuilder, value: []const u8) *RequestBuilder

// Set the request's protocol version
fn version(self: *RequestBuilder, value: Version) *RequestBuilder

Response

An HTTP response object produced by the response builder.

const Response = struct {
    status: StatusCode,
    version: Version,
    headers: Headers,
    body: []const u8,
};

// The default constructor to start building a response
fn builder(allocator: *Allocator) ResponseBuilder

ResponseBuilder

The response builder.

// The default constructor
default(allocator: *Allocator) ResponseBuilder

// Set the response's payload.
// This function returns the final response objet or a potential error
// collected during the build steps
fn body(self: *ResponseBuilder, value: []const u8) ResponseError!Response

// Set a response header name and value
fn header(self: *ResponseBuilder, name: []const u8, value: []const u8) *ResponseBuilder

// Set the response's status code
fn status(self: *ResponseBuilder, value: StatusCode) *ResponseBuilder

// Set the response's protocol version
fn version(self: *ResponseBuilder, value: Version) *ResponseBuilder

Uri

A valid URI object

Read more

Enumerations

Method

The available request methods.

• Connect
• Custom
• Delete
• Get
• Head
• Options
• Patch
• Post
• Put
• Trace

StatusCode

The available response status codes.

A lot; the list is available on MDN.

Version

The available protocol versions.

• Http09
• Http10
• Http11
• Http2
• Http3

Errors

HeadersError

• OutOfMemory
• Invalid

RequestError

• OutOfMemory
• UriRequired
• URI errors

ResponseError

• OutOfMemory

License

http is released under the BSD Zero clause license. 🎉🍻

The URI parser is a fork of Vexu's zuri under the MIT License.