txt: ## dist_zef-raku-community-modules-HTTP-Server-Async.md
  [![Actions Status](https://github.com/raku-community-modules/HTTP-Server-Async/actions/workflows/test.yml/badge.svg)](https://github.com/raku-community-modules/HTTP-Server-Async/actions)
  
  # NAME
  
  HTTP::Server::Async - Asynchronous Base HTTP Server
  
  # SYNOPSIS
  
  ```
  use HTTP::Server::Async;
  
  my $s = HTTP::Server::Async.new;
  
  $s.handler:  -> $request, $response {
      $response.headers<Content-Type> = 'text/plain';
      $response.status = 200;
      $response.write("Hello ");
      # keeps a promise in the response and ends the server handler processing
      $response.close("world!");
  }
  
  $s.listen(True);
  
  ```
  
  # DESCRIPTION
  
  HTTP::Server::Async provides an implementation of an HTTP server, based on the roles provided by `HTTP::Roles`.
  
  It currently handles:
  
  * Parsing Headers
  * Chunked Transfer
  * Hooks for middleware or route handling
  * Simple response handling
  
  It does **not** handle:
  
  * ~~Route handling~~ (See [`HTTP::Server::Router`](https://github.com/tony-o/perl6-http-server-router))
  * ~~File transfers~~
  
  # CLASSES
  
  ## HTTP::Server::Async
  
  ### new
  
  Takes these named arguments to return an instantiated object:
  
  * :port - port to listen on
  * :host - IP number to listen on
  * :buffered - whether responses should be buffered or not (Bool)
  
  ### handler
  
  Any `Callable` passed to this method is registered to be called on every incoming request in the order in which they were registered.
  
  Any registered `Callable` should return `True` to continue processing. A `False` value will discontinue processing of the request. Alternatively a `Promise` can be returned: if the `Promise` is broken then the server will discontinue, if the promise is kept then processing will continue.
  
  The `Callable` will receive two parameters from the server, an `HTTP::Server::Async::Request` and a `HTTP::Server::Async::Response` object. More about the `Response` and `Request` object below.
  
  Note that the server will wait for the request body to be complete before calling `Callable` registered with `handler`.
  
  ### middleware
  
  The same as the `handler` except will **NOT** wait for a complete request body. The middleware can hijack the connection by explicitly returning `False` and continuing processing using `$request.connection` to gain control of the socket.
  
  ### listen
  
  Starts the server and does **not** block, unless called with a `True` value.
  
  ## HTTP::Server::Async::Request
  
  This handles the parsing of an incoming request.
  
  ### Attributes
  
  #### method
  
  GET/PUT/POST/etc.
  
  #### headers
  
  hash with Key/value pair containing the header values.
  
  #### uri
  
  Requested resource.
  
  #### version
  
  HTTP/1.X (or whatever was in the request).
  
  #### data
  
  String containing the data included with the request.
  
  ## HTTP::Server::Async::Response
  
  Response object, handles writing and closing the socket.
  
  ### Attributes
  
  #### buffered
  
  Whether or not the response object should buffer the response and write on close, or write directly to the socket.
  
  #### status
  
  Set the status of the response, uses HTTP status codes. See [RFC2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) for more information. Defaults to 200.
  
  #### headers
  
  Hash with response headers to be sent, accessed directly. Modifying these after writing to the socket will have no effect on the response unless the `buffered` is set to True.
  
  ### Methods
  
  #### write
  
  Write data to the socket, will call the appropriate method for the socket (`$connection.write` for `Str`s, anything else is `$connection.send`)
  
  #### close
  
  Close takes optional parameter of data to send out. Will call `write` if a parameter is provided. Closes the socket, writes headers if the response is buffered, etc.
  
  # CREDITS
  
  Thanks to ugexe, btyler, jnthn, and timotimo for helping figure out bugs, answer a bunch of questions, etc.
  
  # AUTHOR
  
  Tony O'Dell
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2014 - 2019 Tony O'Dell
  
  Copyright 2020 - 2022 Raku Community
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  