diff --git a/docs/deployment-tips.md b/docs/deployment-tips.md new file mode 100644 index 0000000..dc3dfcb --- /dev/null +++ b/docs/deployment-tips.md @@ -0,0 +1,11 @@ +# Deployment Tips + +Now that you've gone and done the hard work of making your very own HTTP server, it's time to go and share it with the world. + +This page contains a list of tips that should help you get the most out of your server when it's deployed somewhere. + +1. Use [LDC](https://github.com/ldc-developers/ldc) to compile the release version of your application. Compile times with LDC are a little longer than with DMD, but you get much better performance, and better compatibility with various OS/arch combinations because the project is based on LLVM. +2. If using the [`TaskPoolHttp1Transport`](transport.md#task-pool-http-1-transport), tune the number of workers according to your needs. For small services, you can usually get by just fine with only 3, and reducing the number of worker threads greatly cuts down on the overall memory footprint of your application. +3. Use a [reverse-proxy](https://en.wikipedia.org/wiki/Reverse_proxy) like [nginx](https://www.nginx.com/) to send traffic to Handy-Http, instead of handling it directly. This is because something like nginx is highly-optimized for maximum performance, and already handles encryption (HTTPS via SSL/TLS). This way, you can focus on the features that improve the quality of the application, instead of worrying about problems others have solved. Also, consider serving static content via reverse-proxy for best performance. +4. Avoid long-duration operations while handling requests. This locks up a worker thread for the duration of the request, so it's best to respond right away (also for the user's experience) and then do additional processing asynchronously. +5. Try to avoid throwing exceptions from your request handlers, where possible. Handle exceptions as soon as they crop up, and set the appropriate HTTP response code instead of relying on Handy-Http's exception handling. Exceptions are quite costly in terms of performance. diff --git a/docs/index.md b/docs/index.md index 04b0d51..479416f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,9 +2,6 @@ Welcome to the documentation site for [Handy-Http](https://git.andrewlalis.com/Handy-Http). Here you'll find guides on how to get started with writing D web servers using Handy-Http, as well as detailed reference documentation for each of the various components that make up the project. -!!! warning - This documentation site is currently a work-in-progress. Please refer to each component's DDoc, or better yet, its source code, for a complete and accurate understanding of what it does. - ## About Handy-Http is a collection of [D lang](https://dlang.org/) source libraries that provide a means for you to run an HTTP server. It started originally as an all-in-one hobby project that [Andrew](https://andrewlalis.com) created a few years ago to escape from the clutches of Java's Spring ecosystem. D offers arguably better developer ergonomics, as well as monumental performance improvements due to its static compilation to machine code. Since its inception, it's gone through a few iterations before settling on the modular architecture presented here. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..961e84b --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,10 @@ +# Testing + +Handy-Http provides a rich set of utilities to make it easy to test the correctness of your request handling logic. + +!!! warning + This page is a work-in-progress. + +## Request & Response Builders + +The [Primitives](primitives.md) component provides a [`ServerHttpRequestBuilder`](ddoc/primitives/handy_http_primitives.builder.ServerHttpRequestBuilder.html) and [`ServerHttpResponseBuilder`](ddoc/primitives/handy_http_primitives.builder.ServerHttpResponseBuilder.html) that you can use to set up a mocked request/response context for testing your [`HttpRequestHandler`](ddoc/primitives/handy_http_primitives.handler.HttpRequestHandler.html) implementations. Each builder provides a fluent interface for setting various properties, including input and output streams. diff --git a/mkdocs.yml b/mkdocs.yml index c35e884..375576a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,8 @@ nav: - Handlers: handlers.md - Data: data.md - Websockets: websockets.md + - Testing: testing.md + - Deployment Tips: deployment-tips.md theme: name: material