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 anymore. Feel free to fork or borrow some ideas if there are any good ones :)

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.