# 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.