civetweb/docs/Interface_Changes_1.10.md

Interface changes

Proposed interface changes for future versions

Interface changes from 1.10 to 1.11 and/or later versions - see also this GitHub issue.

Server interface

S1: mg_start / mg_init_library

Calling mg_init_library is recommended before calling mg_start.

Compatibility considerations: Initially, mg_init_library will be called implicitly if it has not been called before mg_start. If mg_init_library was not called, mg_stop may leave memory leaks.

Required Actions: Call mg_init_library manually to avoid a small memory leak when closing the server.

S2: mg_websocket_write functions

Calling mg_lock_connection is no longer called implicitly in mg_websocket_write functions. If you use websocket write functions them from two threads, you must call mg_lock_connection explicitly, just like for any other connection.

This is an API harmonization issue.

Compatibility considerations: If a websocket connection was used in only one thread, there is no incompatibility. If a websocket connection was used in multiple threads, the user has to add the mg_lock_connection before and the mg_unlock_connection after the websocket write call.

Required Actions: Call mg_lock_connection and mg_unlock_connection manually when using mg_websocket_write.

S3: open_file member of mg_callbacks

Memory mapped files are a relic from before mg_set_request_handler was introduced in CivetWeb 1.4 (September 2013). Is "file in memory" still a useful feature or dead code? See this discussion. Since it is not widely used, and a burden in maintenance, the "file in memory" should be completely removed, including removing the open_file member of mg_callbacks.

Compatibility considerations: Removing "file in memory" will require code using open_file to be changed. A possible replacement by mg_set_request_handler is sketched in this comment.

Required Actions: Modify code using open_file by using request handlers.

S4: Support multiple hostnames and SNI

TLS Server Name Identification (SNI) allows to host different domains with different X.509 certificates on the same physical server (same IP+port). In order to support this, some configurations (like authentication_domain, ssl_certificate, document_root and may others) need to be specified multiple times - once for each domain hosted (see 535).

The current configuration model does not account for SNI, so it needs to be extended to support configuration of multiple instances.

Compatibility considerations: To be defined as soon as possible solutions are evaluated.

S5: IPv6 support for access_control_list and throttle

The current configuration for access_control_list and throttle only works for IPv4 addresses. If server and client support IPv6 as well, there is no way to add a client to the throttle or access list. The current configuration syntax isn't really comfortable for IPv4 either. Combined with hosting multiple domains (and SNI), different domains may have different block/throttle configurations as well - this has to be considered in a new configuration as well.

Compatibility considerations: To be defined as soon as possible solutions are evaluated.

Client interface

C1: mg_init_library

Calling mg_init_library is required before calling any client function. In particular, the TLS initialization must be done before using mg_connect_client_secure.

Compatibility considerations: Some parts of the client interface did not work, if mg_start was not called before. Now it works after calling mg_init_library - this is not an incompatibility.

C2: mg_connect_client (family)

mg_connect_client needs several new parameters (options).

Details are to be defined.

mg_connect_client and mg_download should return a different kind of mg_connection than used in server callbacks. At least, there should be a function mg_get_response_info, instead of using mg_get_request_info, and getting the HTTP response code from the server by looking into the uri member of struct mg_request_info.

General interfaces

G1: size_t in all interface

Having size_t in interfaces while building for 32 and 64 bit complicates maintenance in an unnecessary way (see 498).

Replace all data sizes by 64 bit integers.

G2: Pattern definition

The current definition of pattern matching is problematic (see 499).

Find and implement a new definition.