56 lines
3.7 KiB
Markdown
56 lines
3.7 KiB
Markdown
# Home
|
|
|
|
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.
|
|
|
|
Handy-Http has been deployed to serve a number of different uses by Andrew and others. For example, Andrew has built the following applications using it:
|
|
|
|
* [Finnow](https://git.andrewlalis.com/andrew/finnow), a personal finance web application for tracking accounts across different financial institutions.
|
|
* [Teacher Tools](https://git.andrewlalis.com/andrew/teacher-tools), a web application with a suite of tools for helping teachers with mundane tasks like attendance and behavior tracking.
|
|
* [LiteList](https://git.andrewlalis.com/andrew/litelist), Andrew's "todo app" made with Handy-Http and a Vue 3 frontend.
|
|
|
|
## Your First Server
|
|
|
|
The easiest way to get started is to use the [starter](https://git.andrewlalis.com/Handy-Http/starter) dependency, which automatically includes the components needed to boot up a simple HTTP server.
|
|
|
|
In the example below, we create a new D project named **my-server**, and add the `handy-http-starter` dependency to it.
|
|
```shell
|
|
dub init my-server
|
|
cd my-server
|
|
dub add handy-http-starter
|
|
```
|
|
|
|
Then, edit your main D function like so:
|
|
```d title="main.d"
|
|
import handy_http_starter;
|
|
|
|
void main() {
|
|
startServer((ref request, ref response) {
|
|
response.headers.add("Content-Type", "text/plain");
|
|
response.headers.add("Content-Length", "12");
|
|
response.outputStream.write(cast(ubyte[]) "Hello world!")
|
|
});
|
|
}
|
|
```
|
|
|
|
In the above code, we take advantage of Handy-Http Starter's shortcuts to quickly boot up an HTTP server on `http://localhost:8080` that responds to any request with `Hello world!`, by executing the provided [delegate function](https://tour.dlang.org/tour/en/basics/delegates) whenever a request is received.
|
|
|
|
## Next Steps
|
|
|
|
Now that you're able to build and run a basic HTTP server, read further on the different parts of Handy-Http to get a deeper understanding of how to build a production-ready application. Start by reading about [Primitives](primitives.md), and then [Transport](transport.md).
|
|
|
|
## Contributing
|
|
|
|
Contributions are very welcome! If you need to, please [ask Andrew](https://andrewlalis.com/contact) to give you an account for [git.andrewlalis.com](https://git.andrewlalis.com) so that you can submit issues and create pull requests. Otherwise, simply send a message to Andrew regarding your concern or improvement if you don't want to bother with creating an account.
|
|
|
|
!!! info
|
|
Due to personal reasons, the author of Handy-Http, Andrew, has chosen not to host the project's source code on GitHub, and instead it's hosted in his own personal project site, [git.andrewlalis.com](https://git.andrewlalis.com). To allow for publishing on [code.dlang.org](https://code.dlang.org), select repositories are mirrored to GitHub.
|
|
|
|
|