6d74d31ecd
This is a dependency of our upcoming web-based material debugger. This
CL also includes `tnt/CMakeLists.txt`, which builds a static lib in a
minimal configuration that enables WebSocket support. The entire library
is built from only 4 files:
${PUBLIC_HDR_DIR}/CivetServer.h
${PUBLIC_HDR_DIR}/civetweb.h
${SRC_DIR}/civetweb.c
${SRC_DIR}/CivetServer.cpp
145 lines
4.8 KiB
Markdown
145 lines
4.8 KiB
Markdown
# 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](https://github.com/civetweb/civetweb/issues/544).
|
|
|
|
|
|
### 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](https://groups.google.com/forum/#!topic/civetweb/h9HT4CmeYqI).
|
|
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](https://github.com/civetweb/civetweb/issues/440#issuecomment-290531238).
|
|
|
|
**Required Actions:**
|
|
Modify code using open\_file by using request handlers.
|
|
|
|
|
|
#### S4: Support multiple hostnames and SNI
|
|
|
|
TLS [Server Name Identification (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication)
|
|
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](https://github.com/civetweb/civetweb/issues/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](https://en.wikipedia.org/wiki/IPv6_address) 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](https://github.com/civetweb/civetweb/issues/498)).
|
|
|
|
Replace all data sizes by 64 bit integers.
|
|
|
|
|
|
#### G2: Pattern definition
|
|
|
|
The current definition of pattern matching is problematic
|
|
(see [499](https://github.com/civetweb/civetweb/issues/499)).
|
|
|
|
Find and implement a new definition.
|
|
|
|
|