mirror of
https://github.com/DaedalusX64/daedalus.git
synced 2025-04-02 10:21:48 -04:00
831be5b995
*Fixed debug build when DAEDALUS_DEBUG_DISPLAYLIST its defined, also I enabled it for debug builds *Fixed ptr->u32 cast in DLParser_DumpVtxInfoDKR, it was causing a compilation error for me) *Removed unsused zlib from third_party, also added webby
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
|
|
# Webby - A simple web server for game debugging #
|
|
|
|
Webby is a web server intended for debugging tools inside a game or other
|
|
program with a continously running main loop. It's intended to be used when
|
|
all you need is something tiny and performance isn't a key concern.
|
|
|
|
## Features ##
|
|
|
|
- No dynamic memory allocations -- server memory is completely fixed
|
|
- No threading, all I/O and serving happens on the calling thread
|
|
- Supports socket keep-alives
|
|
- Supports the 100-Continue scheme for file uploading
|
|
- Basic support for WebSockets is available.
|
|
|
|
Because request/response I/O is synchronous on the calling thread, performance
|
|
will suffer when you are serving data. For the use-cases Webby is intended for,
|
|
this is fine. You can still run Webby in a background thread at your
|
|
discretion if this is a problem.
|
|
|
|
## Usage ##
|
|
|
|
- Fill in a `WebbyServerConfig` structure
|
|
- Compute the memory requirements by calling `WebbyServerMemoryNeeded()`
|
|
- Allocate memory (or just use a static char array..)
|
|
- Initialize the server by calling `WebbyServerInit()`
|
|
- Every game frame, call `WebbyServerUpdate()`
|
|
- Handle requests in your dispatch function
|
|
- When it's time to shut down, call `WebbyServerShutdown()`
|
|
|
|
## WebSocket Usage ##
|
|
|
|
- Provide the `WEBBY_SERVER_WEBSOCKETS` flag at init time
|
|
- In your `ws_connect` handler, decide to allow the upgrade request.
|
|
- When the connection is established, your `ws_connected` handler is called. At this point, you can start sending WebSocket frames over the connection (and you can get incoming frames as well).
|
|
- As frames come in, your `ws_frame` handler will be called. Webby doesn't try to merge frames together when the data is split into fragments, so you can be getting one binary/text frame followed by any number of continuation frames. It's up to your handler to make sense of the data and build a buffer as appropriate. The rationale is that otherwise Webby would need a lot more buffer space. To read the frame data, look at the payload size and then call `WebbyRead` to get at the data. Be careful to not read more than what is stated, or you will screw up the protocol.
|
|
- To send WebSocket data, call `WebbyBeginSocketFrame`, passing in the type of frame (typically `WEBBY_WS_OP_TEXT_FRAME` or `WEBBY_WS_OP_BINARY_FRAME`). Then write an arbitrary amount of data using `WebbyWrite`. When you're done, call `WebbyEndSocketFrame`. Webby currently emits one WebSocket (continuation) frame for each `WebbyWrite` call (again, to reduce buffering overhead), so try to write big chunks if you can.
|
|
- When a connection is closed, you will get a call to your `ws_closed` handler.
|
|
|
|
## Request handling ##
|
|
|
|
When you configure the server, you give it a function pointer to your
|
|
dispatcher. The dispatcher is called by Webby when a request has been fully
|
|
read into memory and is ready for processing. The socket the request came in on
|
|
has then been switched to blocking mode, and you're free to read any request
|
|
data using `WebbyRead()` (if present, check `content_length`) and then write
|
|
your response.
|
|
|
|
There are two ways to generate a response; explicit size or chunked.
|
|
|
|
### When you know the size of the data ###
|
|
|
|
When you know in advance how big the response is going to be, you should pass
|
|
that size in bytes to `WebbyBeginResponse()` (it will be sent as the
|
|
Content-Length header). You then call `WebbyWrite()` to push that data out, and
|
|
finally `WebbyEndResponse()` to finalize the response and prepare the socket
|
|
for a new request.
|
|
|
|
### When the response size is dynamic ###
|
|
|
|
Sometimes you want to generate an arbitrary amount of text in the response, and
|
|
you don't know how much that will be. Rather than buffering everything in RAM,
|
|
you can use chunked encoding. First call `WebbyBeginResponse()` as normal, but
|
|
pass it -1 for the content length. This triggers sending the
|
|
`Transfer-Encoding: chunked` header. You then call `WebbyWrite()` or
|
|
`WebbyPrintf()` as desired until the response is complete. When you're done,
|
|
call `WebbyEndResponse()` to finish up.
|
|
|
|
## Limitations ##
|
|
|
|
- There is not much error checking.
|
|
|
|
## Author ##
|
|
|
|
Webby was written by Andreas Fredriksson (@deplinenoise on Twitter).
|
|
|
|
## License ##
|
|
|
|
Webby is available under the BSD license. See the file `LICENSE`.
|