Alfred #

A performant, expressjs like server framework thats easy to use and has all the bits in one place.

Quickstart:

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.get('/example', (req, res) => 'Hello world');

  await app.listen();
}

Index #

Core principles
Usage overview
- Quick start guide
Routing & incoming requests
Middleware
- No 'next'?
- CORS
Responses
Error handling
- 404 Handling
Databases
What I want to do isn't listed
Websockets
Logging
- Print routes
Multi threading & isolates
Contributions

Core principles #

A minimum of dependencies,
A minimum of code and sticking close to dart core libraries - easy to maintain!
Ease of use
Predictable, well established semantics
90%+ of everything you need all ready to go

Read about the background behind the project or why its different to shelf

Usage overview #

If you have ever used expressjs before you should be right at home:

import 'dart:io';

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.get('/text', (req, res) => 'Text response');

  app.get('/json', (req, res) => {'json_response': true});

  app.get('/jsonExpressStyle', (req, res) {
    res.json({'type': 'traditional_json_response'});
  });

  app.get('/file', (req, res) => File('test/files/image.jpg'));

  app.get('/html', (req, res) {
    res.headers.contentType = ContentType.html;
    return '<html><body><h1>Test HTML</h1></body></html>';
  });

  await app.listen(6565); //Listening on port 6565
}

It should do pretty much what you expect. Handling bodies though do need an "await":

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.post('/post-route', (req, res) async {
    final body = await req.body; //JSON body
    body != null; //true
  });

  await app.listen(); //Listening on port 3000
}

Internally dart provides a body parser, so no extra dependencies there.

The big difference you will see is the option to not call res.send or res.json etc - although you still can. Each route accepts a Future as response. Currently you can pass back the following and it will be sent appropriately:

Return Dart Type	Returning REST type
`List<dynamic>`	JSON
`Map<String, Object?>`	JSON
Serializable object (Object.toJSON or Object.toJson) * see note	JSON
`String`	Plain Text
`Stream<List<int>>`	Binary
`List<int>`	Binary
`File`	Binary, with mime type inferred by extension
`Directory`	Serves static files

* If your object has a "toJSON" or "toJson" function, alfred will run it, and then return the result

If you want to return HTML, just set the content type to HTML like this:

import 'dart:io';

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.get('/html', (req, res) {
    res.headers.contentType = ContentType.html;
    return '<html><body><h1>Title!</h1></body></html>';
  });

  await app.listen(); //Listening on port 3000
}

If you want to return a different type and have it handled automatically, you can extend Alfred with custom type handlers.

Quick start guide #

If its all a bit overwhelming @iapicca put together a quick start guide which goes into a little more detail: https://medium.com/@iapicca/alfred-an-express-like-server-framework-written-in-dart-1661e8963db9

Routing & incoming requests #

Routing follows a similar pattern to the more basic ExpressJS routes. While there is some regex matching, mostly just stick with the route name and param syntax from Express:

"/path/to/:id/property" etc

So for example:

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();
  app.all('/example/:id/:name', (req, res) {
    req.params['id'] != null;
    req.params['name'] != null;
  });
  await app.listen();
}

You can also use a wildcard for a route, and provided another route hasn't already resolved the response it will be hit. So for example if you want to authenticate a whole section of an api youc can do this:

import 'dart:async';
import 'dart:io';

import 'package:alfred/alfred.dart';

FutureOr _authenticationMiddleware(HttpRequest req, HttpResponse res) async {
  res.statusCode = 401;
  await res.close();
}

void main() async {
  final app = Alfred();

  app.all('/resource*', (req, res) => _authenticationMiddleware);

  app.get('/resource', (req, res) {}); //Will not be hit
  app.post('/resource', (req, res) {}); //Will not be hit
  app.post('/resource/1', (req, res) {}); //Will not be hit

  await app.listen();
}

Route params #

You can access any params for routes from the req.params object as below:

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();
  app.all('/example/:id/:name', (req, res) {
    req.params['id'] != null;
    req.params['name'] != null;
  });
  await app.listen();
}

Query string variables #

Querystring variables are exposed req.uri.queryParameters object in the request as below:

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.post('/route', (req, res) async {
    /// Handle /route?qsvar=true
    final result = req.uri.queryParameters['qsvar'];
    result == 'true'; //true
  });

  await app.listen(); //Listening on port 3000
}

Body parsing #

To access the body, simply call await req.body.

Alfred will interpret the body type from the content type headers and parse it appropriately. It handles url encoded, multipart & json bodies out of the box.

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.post('/post-route', (req, res) async {
    final body = await req.body; //JSON body
    body != null; //true
  });

  await app.listen(); //Listening on port 3000
}

File uploads #

To upload a file the body parser will handle exposing the data you need. Its actually pretty easy just give it a go and set a breakpoint to see what the body parser spits back.

A working example of file uploads is below to get you started:

import 'dart:io';

import 'package:alfred/alfred.dart';

final _uploadDirectory = Directory('uploadedFiles');

Future<void> main() async {
  final app = Alfred();

  app.get('/files/*', (req, res) => _uploadDirectory);

  /// Example of handling a multipart/form-data file upload
  app.post(
      '/upload',
      (req, res) => (HttpRequest req, HttpResponse res) async {
            final body = await req.bodyAsJsonMap;

            // Create the upload directory if it doesn't exist
            if (await _uploadDirectory.exists() == false) {
              await _uploadDirectory.create();
            }

            // Get the uploaded file content
            final uploadedFile = (body['file'] as HttpBodyFileUpload);
            var fileBytes = (uploadedFile.content as List<int>);

            // Create the local file name and save the file
            await File('${_uploadDirectory.absolute}/${uploadedFile.filename}')
                .writeAsBytes(fileBytes);

            /// Return the path to the user
            ///
            /// The path is served from the /files route above
            return ({
              'path':
                  'https://${req.headers.host ?? ''}/files/${uploadedFile.filename}'
            });
          });

  await app.listen();
}

Middleware #

You can specify a middleware for all routes by using wildcards:

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();
  app.all('*', (req, res) {
    // Perform action
    req.headers.add('x-custom-header', "Alfred isn't bad");

    /// No need to call next as we don't send a response.
    /// Alfred will find the next matching route
  });

  app.get('/otherFunction', (req, res) {
    //Action performed next
    return {'message': 'complete'};
  });

  await app.listen();
}

Middleware declared this way will be executed in the order its added to the app.

You can also add middleware to a route, this is great to enforce authentication etc on an endpoint:

import 'dart:async';
import 'dart:io';

import 'package:alfred/alfred.dart';

FutureOr exampleMiddlware(HttpRequest req, HttpResponse res) {
  // Do work
  if (req.headers.value('Authorization') != 'apikey') {
    throw AlfredException(401, {'message': 'authentication failed'});
  }
}

void main() async {
  final app = Alfred();
  app.all('/example/:id/:name', (req, res) {}, middleware: [exampleMiddlware]);

  await app.listen(); //Listening on port 3000
}

What? No 'next'? how do I even? #

OK, so the rules are simple. If a middleware resolves a http request, no future middleware gets executed.

So if you return an object from the middleware, you are preventing future middleware from executing.

If you return null it will yield to the next middleware or route.

** returning null is the equivalent of 'next' **

CORS #

There is a cors middleware supplied for your convenience. Its also a great example of how to write a middleware for Alfred

import 'package:alfred/alfred.dart';
import 'package:alfred/src/middleware/cors.dart';

void main() async {
  final app = Alfred();

  // Warning: defaults to origin "*"
  app.all('*', cors(origin: 'myorigin.com'));

  await app.listen();
}

Responses #

Alfred is super easy, generally you just return JSON, a file, a String or a Binary stream and you are all good.

The big difference from express is you will see is the option to not call res.send or res.json etc - although you still can. Each route accepts a Future as response. Currently you can pass back the following and it will be sent appropriately:

List<dynamic> - JSON
Map<String, Object?> - JSON
String - Plain text
Stream<List<int>> - Binary
List<int> - Binary
File - Binary, with mime type inferred by extension
Directory - Serves static files

Each type listed above has a Type Handler build in. You can create your own custom type handlers

Custom type handlers #

Alfred has a pretty cool mechanism thanks to Dart's type system to automatically resolve a response based on the returned type from a route. These are called Type Handlers.

If you want to create custom type handlers, just add them to the type handler array in the app object. This is a bit advanced, and I expect it would be more for devs wanting to extend Alfred:

import 'package:alfred/alfred.dart';

class Chicken {
  String get response => 'I am a chicken';
}

void main() {
  final app = Alfred();

  app.typeHandlers.add(TypeHandler<Chicken>((req, res, dynamic val) async {
    res.write((val as Chicken).response);
    await res.close();
  }));

  /// The app will now return the Chicken.response if you return one from a route

  app.get('/kfc', (req, res) => Chicken()); //I am a chicken;

  app.listen(); //Listening on 3000
}

Static Files #

This one is super easy - just pass in a public path and a dart Directory object and Alfred does the rest.

import 'dart:io';

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  /// Note the wildcard (*) this is very important!!
  app.get('/public/*', (req, res) => Directory('test/files'));

  await app.listen();
}

File downloads #

As mentioned above - if you want to return a file, simply return it from the route callback. However the browser will probably try to render it in browser, and not download it.

You can just set the right headers, but there is a handy little helper that will do it all for you.

See res.setDownload below.

import 'dart:io';

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.get('/image/download', (req, res) {
    res.setDownload(filename: 'image.jpg');
    return File('test/files/image.jpg');
  });

  await app.listen(); //Listening on port 3000
}

Error handling #

You can either set the status code on the response object yourself and send the data manually, or you can do this from any route:

app.get("/",(req, res) => throw AlfredException(400, {"message": "invalid request"}));

If any of the routes bubble an unhandled error, it will catch it and throw a 500 error.

If you want to handle the logic when a 500 error is thrown, you can add a custom handler when you instantiate the app. For example:

import 'dart:async';

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred(onInternalError: errorHandler);
  await app.listen();
  app.get('/throwserror', (req, res) => throw Exception('generic exception'));
}

FutureOr errorHandler(HttpRequest req, HttpResponse res) {
  res.statusCode = 500;
  return {'message': 'error not handled'};
}

404 Handling #

404 Handling works the same as 500 error handling (or uncaught error handling). There is a default behaviour, but if you want to override it, simply handle it in the app declaration.

import 'dart:async';
import 'dart:io';

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred(onNotFound: missingHandler);
  await app.listen();
}

FutureOr missingHandler(HttpRequest req, HttpResponse res) {
  res.statusCode = 404;
  return {'message': 'not found'};
}

But what about Mongo or Postgres or

The other two systems that inspired this project to be kicked off - Aqueduct and Angel - both had some sort of database integration built in.

You do not need this.

Access the dart drivers for the database system you want directly, they all use them behind the scenes:

Mongo - https://pub.dev/packages/mongo_dart
Postgres - https://pub.dev/packages/postgres
SQLLite - https://pub.dev/packages/sqlite3

You will be fine. I have used them this way and they work.

I have rolled my own classes that act as a sort of ORM, especially around Mongo. Its suprisingly effective and doesn't rely on much code.

What I want to do isn't listed #

While there are bunch of helpers built in - you have direct access to the low level apis available from the dart:io package. All helpers are just extension methods to:

HttpRequest: https://api.dart.dev/stable/2.10.5/dart-io/HttpRequest-class.html
HttpResponse: https://api.dart.dev/stable/2.10.5/dart-io/HttpResponse-class.html

So you can compose and write any content you can imagine there. If there is something you wan't to do that isn't expressly listed by the library, you will be able to do it with a minimum of research into underlying libraries. A core part of the architecture is to not build you into a wall.

Websockets #

Alfred supports websockets too!

There is a quick chat client in the examples

import 'dart:async';
import 'dart:io';

import 'package:alfred/alfred.dart';
import 'package:alfred/src/type_handlers/websocket_type_handler.dart';

Future<void> main() async {
  final app = Alfred();

  // Path to this Dart file
  var dir = File(Platform.script.path).parent.path;

  // Deliver web client for chat
  app.get('/', (req, res) => File('$dir/chat-client.html'));

  // Track connected clients
  var users = <WebSocket>[];

  // WebSocket chat relay implementation
  app.get('/ws', (req, res) {
    return WebSocketSession(
      onOpen: (ws) {
        users.add(ws);
        users
            .where((user) => user != ws)
            .forEach((user) => user.send('A new user joined the chat.'));
      },
      onClose: (ws) {
        users.remove(ws);
        users.forEach((user) => user.send('A user has left.'));
      },
      onMessage: (ws, dynamic data) async {
        users.forEach((user) => user.send(data));
      },
    );
  });

  final server = await app.listen();

  print('Listening on ${server.port}');
}

Logging #

For more details on logging click here.

Print routes #

Want to quickly print out the registered routes? (recommended when you fire up the server) call Alfred.printRoutes ie:

import 'package:alfred/alfred.dart';

void main() async {
  final app = Alfred();

  app.get('/html', (req, res) {});

  app.printRoutes(); //Will print the routes to the console

  await app.listen();
}

Multi threading and isolates #

You can use the app in multithreaded mode. When spawning this way, requests are evenly distributed amongst the various isolates. Alfred is not particularly prescriptive about how you manage the isolates just that "it works" when you fire up multiples.

import 'dart:isolate';

import 'package:alfred/alfred.dart';

Future<void> main() async {
  // Fire up 5 isolates
  for (var i = 0; i < 5; i++) {
    unawaited(Isolate.spawn(startInstance, ''));
  }
  // Start listening on this isolate also
  startInstance(null);
}

/// The start function needs to be top level or static. You probably want to
/// run your entire app in an isolate so you don't run into trouble sharing DB
/// connections etc. However you can engineer this however you like.
///
void startInstance(dynamic message) async {
  final app = Alfred();

  app.all('/example', (req, res) => 'Hello world');

  await app.listen();
}

/// Simple function to prevent linting errors, can be ignored
void unawaited(Future future) {}

Contributions #

PRs are welcome and encouraged! This is a community project and as long as the PR keeps within the key principles listed it will probably be accepted. If you have an improvement you would like to to add but are not sure just reach out in the issues section.

Before you submit your code, you can run the ci_checks.sh shell script that will do many of the tests the CI suite will perform.

alfred 0.1.4+2
alfred: ^0.1.4+2 copied to clipboard

Metadata

Alfred #

Index #

Core principles #

Usage overview #

Quick start guide #

Routing & incoming requests #

Route params #

Query string variables #

Body parsing #

File uploads #

Middleware #

What? No 'next'? how do I even? #

CORS #

Responses #

Custom type handlers #

Static Files #

File downloads #

Error handling #

404 Handling #

But what about Mongo or Postgres or

What I want to do isn't listed #

Websockets #

Logging #

Print routes #

Multi threading and isolates #

Contributions #

← Metadata

Publisher

Metadata

License

Dependencies

More

alfred 0.1.4+2 alfred: ^0.1.4+2 copied to clipboard

Metadata

Alfred #

Index #

Core principles #

Usage overview #

Quick start guide #

Routing & incoming requests #

Route params #

Query string variables #

Body parsing #

File uploads #

Middleware #

What? No 'next'? how do I even? #

CORS #

Responses #

Custom type handlers #

Static Files #

File downloads #

Error handling #

404 Handling #

But what about Mongo or Postgres or

What I want to do isn't listed #

Websockets #

Logging #

Print routes #

Multi threading and isolates #

Contributions #

← Metadata

Publisher

Metadata

License

Dependencies

More

alfred 0.1.4+2
alfred: ^0.1.4+2 copied to clipboard