A low-level API

[LordMZTE]

As previously discussed in #11, Zelda could use a low-level API. I've thought about how an alternative low-level API might look. This is a summary what I had in mind:

// An "interaction" as I chose to call it here is basically a handle to an ongoing request.
var interaction = try client.beginInteraction(
    // URL
    "https://example.com",

    // request type
    .post,

    // advanced options struct. Below are some things I'd consider useful here.
    .{
        // This prevents zelda from sending any headers at all.
        // This option would allow for more fine-grained control over the exact request.
        .no_headers = true,
    },
);

// This function could act to both finish a successful request on completion, as well
// as to cleanly abort a request in case something goes wrong during the interaction.
defer interaction.finish();

// This function sends the header to the server here and doesn't just save it.
try interaction.header("Content-Type", "application/my-fancy-data");
try interaction.header("Accept", "application/my-fancy-data");
// TODO: set User-Agent (no_headers = true)

// This function finishes the headers of the request and begins sending the request body.
// If the request has no body, this step is skipped.
var request_body_writer = try interaction.beginRequestBody();

try request_body_writer.writeAll("Hello, Server!");

// This function makes sure the request has been fully sent and waits for the server to answer.
// The type returned by this contains information about the response such as headers, and a reader.
var response = try interaction.awaitResponse();

if (response.code != 200) {
    return error.BadResponse;
}

// response.headers is an iterator over the headers. I'm not sure if it should iterate
// over headers saved in memory, or if it should instead read them while it's being iterated.
while (response.headers.next()) |header| {
    std.log.debug("response header: {s}: {s}", .{header.key, header.value});
}

// TODO: read response data from response.reader

I'm very much looking for feedback on this proposed API, it's just a rough outline of what I think might be a flexible and powerful low-level API.

Of course, I'm willing to do my part in implementing this once we agree to a way to do this.

Closes #11

[haze]

In my opinion, this looks like a middle level API between hzzp (the http parser Zelda uses) and Zelda itself. I think I'd prefer this as a separate package, because it reduces the API surface area. I created Zelda for people who just wanted a zig native web request (no cURL.) Of course, if a PR is made to add this, and it doesn't look as cumbersome to maintain and develop with, then I might feel differently

[LordMZTE]

I see. I agree that this might best fit into another library.

[haze]

If you want to fork Zelda as a starting place and create the API around that, you're free to do so