= Development Status: new NetServices Kit

Haiku currently has a 'Network Services Kit' as part of it's standard library. The goal is to provide a standard interface to execute network requests to a variety of protocols, in a way that integrates cleanly with Haiku's API design. The current API has three problems:

1. While the API is designed to be asynchronous, every request spins up in a separate thread, which is an inefficient way of using system resources.
2. The API design is quite prescriptive and does not work well for all protocols. There are known issues implementing the FTP protocol.
3. The API implemented a callback interface, which executed callbacks within the context of the dedicated request thread. This is problematic, as it does not impose any locking on the code that is executed, and thus invites data races.

The libnetservices2 kit proposes to remedy those issues by providing a new design.

== Resources

The development branch was merged into Haiku as [https://git.haiku-os.org/haiku/commit/?h=hrev56572&id=1111dda699f8093bfdc9b232a919110a1c1b49a7 hrev56572]. A release was bundled with Haiku R1 Beta 4. The latest developments are on the master branch.

== Known issues in Haiku R1 Beta 4

 * When using the option to stop parsing/receiving the HTTP response on a client error (4xx) or server error (5xx) status code, the asynchronous listener would not be notified that the request is finished ([https://git.haiku-os.org/haiku/commit/?id=b70a0efa9e95a3cfdf9e629ab00f2610fc64e162 hrev56641]). The advice is not to use asynchronous listeners in combination with stop on error.

== Status

The Preview of the HTTP Network Services Kit is in a separate static library (`libnetservices2.a`) and therefore can be further refined and developed whilst keeping compatibility with software that uses `libnetservices.a`. 

== To Do

This is a non-exhaustive list of items still to do.

=== Existing Protocols: data, file and gopher protocols

The existing netservices protocols have not all been reimplemented. It is worth discussing/discovering whether that is useful/expected. The focus has been on HTTP initially, because this is the most important protocol in the current age, but there may be value in adding additional protocols.

=== HTTP 2 & 3 Support

Currently the API supports HTTP 1.1 (and should be backward compatible to HTTP 1, though that requires testing!).

[https://developer.mozilla.org/en-US/docs/Glossary/HTTP_2 HTTP 2] is a major evolution of the protocol that is designed primarily to increase the performance of the HTTP transfers by allowing to bundle multiple requests in one stream (multiplexing). The new network services kit uses the concept of a session to handle multiple requests. The session could be a good integration point to support this, though more research and design needs to be put in this.

[https://en.wikipedia.org/wiki/HTTP/3 HTTP 3] is a proposed web standard that implements HTTP over the QUIC protocol, which should reduce latency and fix some of the fundamental issues in HTTP 2. Characteristic of this protocol is that it switched to from TCP to UDP.

=== HTTP protocol

Missing features:
 * Cookies
 * Tools for HTTP forms
 * Multipart requests and responses
 * HTTP Digest Authentication
 * Tools for parsing HTTP field values; there are various ways of interpreting and building values that we could make easier for the user.
 * KeepAlive support (?)
 * SSL certificate error handling
 * Custom SSL certificates
 * HTTP Proxy support

Some smaller improvements:
 * Support for ranges in BHttpRequest.
 * Throw an exception when one wants to schedule an empty BHttpRequest in BHttpSession::Execute().
 * BHttpDate currently references older RFCs, the documentation and constant naming should be updated.


=== General Kit Design

Exceptions:
 * Review the design of BError and the general usefulness of the `origin` property.
 * Review the design of exceptions around invalid input parameters; it feels like there is a more generic approach or a more generic solution there.

The libnetservices2 proposal has a generic `BUrlDownload` interface (see [https://github.com/nielx/haiku-netservices-rfc/tree/exceptions#part-c-introducing-burldownload section C of the proposal]). This is not implemented yet, though one might argue that implementing this only makes sense if multiple protocols are implemented.