h4 0.1.1

A minimal HTTP framework for building elegant server applications.

H4.

A lightweight, minimal, and incredibly fast HTTP framework for productive and fun API development with dart.

This is a new project under active development

Do not use in production as it could break unexpectedly.

There's an express-like server framework called Alfred in the dart ecosystem.

This is the H3 implementation with similar design goals. Special thanks to Pooya Parsa and the Unjs community for making a awesome http library.

Features

• Lightweight: H4 ships with a small core and a set of composable utilities.
• Middleware: H4 comes with built-in onRequest and onError middleware.
• Generic Handlers: Specify the return type of your handler functions.

Getting Started

Add H4 to your pubspec.yaml:

dependencies:
  h4: ^1.0.0

Or install with dart pub get

dart pub add h4

Import the library and start building your server:

import 'package:h4/create.dart';

void main() {
 var app = createApp();
 var router = createRouter();

 app.use(router);

 router.get("/", (event) => "Hello world!");
}

Examples

Manual Start

void main() {
  var app = createApp(port: 4000, autoStart: false);
  var router = createRouter();

  app.use(router);

  router.get("/hi", (event) => "Hi")

  app.start()
}

Generic handlers

Specify the return type of your handlers

router.get<bool>("/25/**", (event) => true);

Middleware

H4 provides two middleware functions out of the box.

// Invoked when a request comes in
app.onRequest((event) {
 print('Incoming request method: ${event.method}');
});

// Global error handler - Called when an error occurs in non-async handlers
app.onError((error) {
 print("$error");
});

Error Handling

You can throw a create error Exception that will terminate the request and send a 400 - Bad Request response

router.get('/error', (event) {
 try {
  // Code that could fail.
 }
 catch(e) {
   throw CreateError(message: 'Womp Womp', errorCode: 400);
 }
});

The client recieves this json payload -

{
 "status": 400,
 "message": "[Error message]"
}

Param Routing

You can define parameters in your routes using : prefix:

router.get('/users/:id', (event) {
 final userId = event.params['id'];
 return 'User $userId'
});

Wildcard Routing

// Matches 'articles/page' and '/articles/otherPage' but not 'articles/page/otherPage'
router.get('/articles/*', (event) {
 final path = event.path;
 return 'The tea is teaing!!'
});

// Matches 'articles/foo/bar' and 'articles/rice/eba/beans'
router.get('/articles/**', (event) {
 final path = event.path;
 return 'The tea is teaing!!'
});

Utilities

A set of composable utilities that help you add functionality to your server

readRequestBody

Reads the request body as json or text depending on the contentType of the request body.

router.post("/vamos", (event) async {
 var body = await readRequestBody(event);
 return body;
});

getHeader

Get the value of any of the incoming request headers. For convenience you can use the HTTPHeaders utility to get header strings.

router.post("/vamos", (event) async {
 var header = getHeader(event, HttpHeaders.userAgentHeader);
 return body;
});

Contributing

Contributors needed!

There's quite a bit of work to do to get H4 to 1.0.0 and ready for production use.

If you find a bug or have an idea for a new feature, please open an issue or submit a pull request.

First Contribution

A good first PR would be helping me improve the test coverage of this library. Or adding one of the utilities listed here.

Running tests

In the root directory run

dart test

Code of Conduct.

Show respect and consideration for others when creating issues and contributing to the library. Only good vibes!