up 0.0.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 57

EARLY RELEASE #

Note that this is a very early-stage release, with no unit tests. Be careful if using it in production at this point.

dart_up

For a managed/hosted solution (truly "serverless"), check out https://dart-up.regios.dev! (this service does not yet exist)

Web application container for Dart servers, akin to PM/2 (Node.js). Runs applications in isolates in the same VM, with .packages files used to provide dependencies. Also supports lambdas, which are lightweight executables run on-demand (and kept alive for an amount of time), instead of long-lived daemons.

dart_up is completely open-source, and aims to make Dart server deployment much simpler. It's essentially a Dart-specific "serverless" container (except, if you're self-hosting, you'll obviously need to provision a server).

Installation #

To install the standalone server:

$ pub global activate dart_up

Usage #

After installing dart_up on your server, deploying a Dart app is as simple as running dart_up push <file>, which creates an app snapshot, and pushes that, along with your pubspec.yaml, to the dart_up daemon. Your application will be spawned in a new isolate, and auto-restarted on crashes/errors.

Create a Lambda #

For example, consider the following hello_lambda.dart:

import 'dart:isolate';
import 'package:dart_up/lambda.dart';

main(_, SendPort sp) {
  return runLambda(
    sp, (req) => Response.text('Hello, lambda world!'));
}

Assuming you have a running dart_up daemon, all you need to do is push an application snapshot:

$ dart_up push --name hello --lambda example/hello_lambda.dart
Building .dart_tool/dart_up/example/hello_lambda.dill... 2.8s
 • hello - dead

Lambdas are dead by default. To trigger a lambda, visit /:name:

$ curl http://localhost:2374/hello; echo
Hello, lambda world!

Create a Daemon #

If the --lambda flag is not passed, then a daemon will created. The given application will be started immediately, and also started whenever dart_up is rebooted. By default, when the application exits (either with success, or an error), it will be re-spawned. This functionality can be disabled by passing the --no-auto-restart flag.

Consider this example:

import 'package:angel_framework/angel_framework.dart';
import 'package:angel_framework/http.dart';

main() async {
  var app = Angel(), http = AngelHttp(app);
  app.fallback((req, res) => 'Hello from dart_up!');
  await http.startServer('127.0.0.1', 3001);
  print('dart_up_example listening at ${http.uri}');
}

Application Management #

The following commands are available for dart_up management (Note: this document may not be up-to-date, especially if new commands are added in the codebase):

$ dart_up --help
Dart Web application container.

Usage: dart_up <command> [arguments]

Global options:
-h, --help    Print this usage information.

Available commands:
  help     Display help information for dart_up.
  kill     Kills a running application.
  list     Lists the status of all active applications within the dart_up instance.
  push     Builds an app snapshot, and pushes it to a dart_up server.
  remove   Kills, and removes an application from the list.
  serve    Launch an HTTP server that manages other Dart applications.
  start    Restarts a dead/inactive process.

Run "dart_up help <command>" for more information about a command.

dart_up push example/my_server.dart will cause dart_up to manage an instance of this application, restarting it if it ever crashes.

For convenience, you can override the default --url option with the DART_UP_URL environment variable:

$ DART_UP_URL=http://example.com dart_up list

Password Authentication #

dart_up supports bcrypt-hashed passwords, and uses Basic authentication to ensure that external clients have access to the daemon. dart_up can also be configured to even required passwords for requests from localhost.

# Set a password. Obviously, be smart about file permissions. Even though
# the passwords are strongly-hashed, the *usernames* are plain text.
$ dart_up password my_username
✔ Password [hidden] ‥ ***********
Successfully edited file .dart_tool/dart_up/passwords.

# Always require Basic authentication, even for localhost.
# Otherwise, it'll only be required for external clients.
$ dart_up serve --require-password

# Disregard `x-forwarded-for` header, i.e. if you're not using nginx `proxy_pass`.
$ dart_up serve --require-password --no-x-forwarded-for

# Any so-called "client command," like `list`, `push`, etc., takes a `--basic-auth`/`-B` option.
# This way, you'll be prompted for a username and password.
$ dart_up list -B
✔ Username ‥ my_username
✔ Password [hidden] ‥ *****
 • hello - dead

Deploying dart_up

You more than likely don't want the dart_up daemon to face the Web. In fact, you might not even want it to be accessible to other processes on the server (in which case you should configure it for password authentication).

That being said, if the dart_up daemon goes down, then logically, all of the applications it's running will become inaccessible. Therefore, you should be sure that in the case dart_up dies, it is immediately restarted. On Ubuntu, using systemd is the best way to do this.

These instructions are pretty abstract, though, because how you deploy dart_up is up to you. The simplest way is to just have a single daemon, and trust all applications running in the VM (i.e. if only your organization is using the server). In a multi-tenant situation, though, running all clients' programs in the same memory space is a recipe for disaster. A better solution is to create users for each client, give each client one separate dart_up process, and use Unix permissions to enforce access control and security.

0.0.1 #

  • Uint8List fix.

0.0.0 #

  • Initial release. No unit tests yet. Be careful using this in production.

example/main.dart

import 'package:angel_framework/angel_framework.dart';
import 'package:angel_framework/http.dart';

main() async {
  var app = Angel(), http = AngelHttp(app);
  app.fallback((req, res) => 'Hello from dart_up!');
  await http.startServer('127.0.0.1', 3001);
  print('dart_up_example listening at ${http.uri}');
}

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate up

2. Use it

The package has the following executables:


$ dart_up

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  up: ^0.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:up/up.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
19
Health:
Code health derived from static analysis. [more]
99
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
57
Learn more about scoring.

We analyzed this package on Dec 9, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.1
  • pana: 0.12.21

Platforms

Detected platforms: other

Primary library: package:up/up.dart with components: io, isolate, mirrors.

Health issues and suggestions

Document public APIs. (-1 points)

44 out of 44 API elements have no dartdoc comment.Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API.

Maintenance suggestions

Package is pre-v0.1 release. (-10 points)

While nothing is inherently wrong with versions of 0.0.*, it might mean that the author is still experimenting with the general direction of the API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
angel_client ^2.0.0 2.0.2
angel_framework ^2.0.0 2.1.0
args ^1.0.0 1.5.2
body_parser ^1.0.0 1.1.1
cli_util ^0.1.3 0.1.3+2
dbcrypt ^1.0.0 1.0.0
http ^0.12.0 0.12.0+2
http_parser ^3.0.0 3.1.3
io ^0.3.2 0.3.3
json_annotation ^3.0.0 3.0.0
json_rpc_2 ^2.0.0 2.1.0
logging ^0.11.0 0.11.3+2
path ^1.0.0 1.6.4
pretty_logging ^1.0.0 1.0.0
prompts ^1.0.0 1.3.1
pubspec_parse ^0.1.5 0.1.5
stream_channel ^2.0.0 2.0.0
yaml ^2.0.0 2.2.0
Transitive dependencies
angel_container 1.1.0
angel_http_exception 1.1.0
angel_model 1.0.3
angel_route 3.1.0+1
async 2.4.0
charcode 1.1.2
checked_yaml 1.0.2
code_buffer 1.0.1
collection 1.14.12
combinator 1.1.0
convert 2.1.1
crypto 2.1.4
dart2_constant 1.0.2+dart2
file 5.1.0
http2 1.0.0
http_server 0.9.8+3
intl 0.16.0
json_god 2.0.0-beta+3
matcher 0.12.6
merge_map 1.0.2
meta 1.1.8
mime 0.9.6+3
mock_request 1.0.6
pub_semver 1.4.2
quiver 2.1.2+1
quiver_hashcode 2.0.0
recase 2.0.1
source_span 1.5.5
stack_trace 1.9.3
string_scanner 1.0.5
term_glyph 1.1.0
tuple 1.0.3
typed_data 1.1.6
uuid 2.0.4
Dev dependencies
build_runner ^1.0.0
json_serializable ^3.0.0
pedantic ^1.0.0 1.9.0