stream 2.2.1+1

  • Readme
  • Changelog
  • Installing
  • 52

Stream #

Stream is a Dart web server supporting request routing, filtering, template engine, WebSocket, MVC design pattern and file-based static resources.

Stream is distributed under an Apache 2.0 License.

Build Status

Installation #

Add this to your pubspec.yaml (or create it):

dependencies:
  stream:

Usage #

Compile RSP (Rikulo Stream Page) to dart files #

There are two ways to compile RSP files into dart files: automatic building with Dart Editor or manual compiling.

RSP is a template technology allowing developers to create dynamically generated web pages based on HTML, XML or other document types (such as this and this). Please refer to here for more information.

Build with Dart Editor #

To compile your RSP files automatically, you just need to add a build.dart file in the root directory of your project, with the following content:

import 'package:stream/rspc.dart';
void main(List<String> arguments) {
  build(arguments);
}

With this build.dart script, whenever your RSP is modified, it will be re-compiled.

Compile Manually #

To compile a RSP file manually, run rspc (RSP compiler) to compile it into the dart file with command line interface as follows:

dart -c lib/rspc.dart -n dir1 dir2 file1 fire2...

A dart file is generated for each RSP file you gave. Fore more options, please run:

dart -c lib/rspc.dart -h

Notes to Contributors #

Fork Stream #

If you'd like to contribute back to the core, you can fork this repository and send us a pull request, when it is ready.

Please be aware that one of Stream's design goals is to keep the sphere of API as neat and consistency as possible. Strong enhancement always demands greater consensus.

If you are new to Git or GitHub, please read this guide first.

Who Uses #

  • Quire - a simple, collaborative, multi-level task management tool.
  • Keikai - a sophisticated spreadsheet for big data

CHANGES #

2.2.1 #

  • Rsp.isHeaderValueValid is added.
  • proxyRequest won't copy request's headers to response's if not valid.

2.2.0 #

  • HttpStatusException, Http500, Http403 and others are changed.

2.1.0 #

  • ScriptTag ([:script]) no longer supported. Use <script> instead.

2.0.3 #

  • HttpConnect.headerValue introduced.

2.0.1 #

  • rpsc.dart enhanced to support folders. Also, it can compile only if source files are modified (the -n option).

2.0.0 #

  • Dart 2 supported

1.7.0 #

  • proxyRequest() introduced to proxy requests to another server

1.6.9 #

  • Allow user to map a URI to another website in router.

1.6.8 #

  • If StreamServer.onError is registered, the default logging will be disabled.

1.6.7 #

  • The line number won't be generated in the output Dart file. To turn it on, specify -n option.

1.6.6 #

  • Http503 introduced.

1.6.5 #

  • Rsp.nnf is deprecated. Recompile all RSP files to remove the use.

1.6.3 #

  • StreamServer.shallCount introduced
  • StreamServer's futureOnly argument is removed.

1.6.1 #

  • StreamServer's futureOnly argument is deprecated.
  • AssetLoader.cache can be set to null (to disable caching).

1.6.0 #

  • DefaultRouter.shallCache introduced

1.5.5 #

  • Server.pathPreprocessor introduced

1.5.2 #

  • [=data, encode: 'json'] is supported
  • LoggingConfigurer is removed
  • StreamServer's constructor is changed: disableLog replaces loggingConfigurer.

1.5.1 #

  • StreamServer.stop and HttpChannel.close returns a Future instance.

1.5.0 #

  • Issue 80: Allow [:include] inside[:for], [:if] and any tag
  • Specifying the etag attribute in the page tag won't imply lastModified="start"

1.3.1 #

  • Issue 79: [:script] supports the async flag

1.3.0 #

  • Issue 78: StreamServer.chunkedTransferEncoding deprecated.
  • The server will be started with runZoned() by default.

1.2.2 #

1.2.0 #

  • Issue 74: StreamServer.onError shall catch all uncaught errors

1.1.0 #

  • The maxlength argument of RspUtil.nnx() is renamed to maxLength.
  • Server.onIdle() and Server.connectionCount are added.

1.0.0 #

December 16, 2013

  • Issue 67: RSP's header directives shall be generated before handling ETAG and Last-Modified

November 20, 2013

  • Issue 61: HttpServer.bind(address, port, backlog: backlog) return null

0.8.7 #

  • The global variables, contentTypes and statusMessages, are moved to Rikulo Commons.

0.8.6+2 #

  • Issue 59: error mapping not work

0.8.5 #

  • Issue 53: FileLoader supports multipart/byteranges
  • Issue 54: Support If-Match, If-None-Match, If-Modified-Since and If-Unmodified-Since
  • Issue 55: Support If-Range
  • Issue 56: Generalize FileLoader to support the loading from different resources, such as database
  • Issue 57: RSP supports etag (and HttpStatus.NOT_MODIFIED)
  • Issue 58: HttpConnect supports method to retrieve the locale(s) of the request

0.8.4 #

  • Issue 51: FileLoader supports partial content, aka., range
  • Issue 52: FileLoader supports ETag and caching

0.8.3 #

  • Issue 49: RSP: Able to generate additional imported packages without specifying them in each RSP file
  • Issue 48: RSP: A tag to simplify the implementation of custom tags s.t. dev needs to implement a closure only

0.8.2 #

  • Channel, HttpChannel and SocketChannel are merged into HttpChannel
  • Issue 47: RSP shall escape $ to prevent Dart from interpreting it.

0.8.1 #

  • Issue 44: The page tag supports the part attribute to include other dart files, and the dart attribute to embed code before the function

0.8.0 #

  • Issue 42: Allow a Stream server to listen multiple addresses/ports and web sockets
  • Issue 43: Allow to map WebSocket directly without invoking WebSocketTransformer explicitly
  • Issue 41: Able to encode the build number into JS and/or CSS s.t. the browse will use the latest JS/CSS automatically

0.7.6 #

  • API changed because of the deprecation of Path

0.7.5 #

  • StreamServer.chunkedTransferEncoding supported for compressing the output with GZIP
  • Issue 38: Unable to use the nested groups in route segments

0.7.4 #

  • Issue 36: Change the spec of [:json] to generate a JSON object that can be parse as Dart object directly
  • Issue 35: A tag for generating the dart script for development, while generating only JS in production
  • HttpConnect.buffer is renamed to HttpConnect.stringBuffer, while HttpConnect.buffer reserved for bytes

0.7.3 #

  • Issue 32: HttpConnect provides API to retrieve the information of the browser
  • Issue 31: RSP supports last-modified as the time it has been compiled
  • Issue 33: The expression tag ([= expr]) supports the encoding option
  • Issue 34: Make the webapp directory optional

0.7.2 #

  • Issue 28: Support the JSON tag for simplifying the rendering of a Dart object
  • Issue 29: The homDir argument shall interpret the relative path against the root directory of the application

0.7.1 #

  • HttpConnect.error has been removed. All errors shall be wired back Future.
  • StreamServer.host can be String or InternetAddress, and the default is ANY_IP_V4.
  • Issue 27: Able to configure Stream server to enforce the return of Future in every handler.

0.7.0 #

  • Issue 16: Make include, forward and handler to return Future if there is any async task
  • Issue 17: include and forward shall handle the query string
  • Issue 24: llow RSP compiler receive a FilenameMapper function to map output files
  • Issue 26: Support HttoConnect.redirect(uri) to redirect to another URI

Upgrade Notes

  1. The request handler must return Future if it spawned an asynchronous task.
  2. The request handler can't return a forwarding URI. Rather, it shall invoke and return connect.forward(uri) instead.
  3. The request handler needs not to close the connection. It is done automatically.
  4. RSP will import dart:async by default.
  5. The request filter must return Future.
  6. The close, onClose and onError methods of HttpConnect are removed. Chaining request handlers is straightforward: it is the same as chaining Future objects.

0.6.2 #

  • Issue 11: Allow URI and filter mapping to be added dynamically

Upgrade Note

  • The syntax of a tag has been changed from [tag] to [:tag]. The old syntax still works but will be removed in the near future.

0.6.1 #

  • Issue 7: Allow URI mapping to be pluggable
  • Issue 8: URI mapping supports RESTful like mapping
  • Issue 9: URI mapping allows to forward to another URI

0.6.0 #

  • [page] introduces the partOf and import attributes
  • [dart] is always generated inside the render function
  • Issue 2: RSP files can be put in the client folder (i.e., not under the webapp folder)
  • Issue 3: [page] partOf accepts a dart file and maintains it automatically
  • Issue 4: Allow to mix expression ([=...]) with literal in tag attributes

0.5.5 #

  • The composite view (aka., templating) is supported.
  • The syntax of the include and forward tags are changed.
  • The var tag is introduced.

0.5.4 #

  • URL mapping supports grouping, such as /user/(name:[^/]*)
  • StreamServer.run() is deprecated. Use start(), startSecure() or startOn() instead.
  • Support the new Dart I/O.

0.5.3 #

  • The filter mapping is supported.
  • HttpConnect.then is removed. Use Future.catchError() instead.

0.5.2 #

  • The error mapping takes the syntax of Map.

0.5.1 #

  • The comment tag is renamed to a pair of [!-- and --]

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate stream

2. Use it

The package has the following executables:


$ rspc

Use this package as a library

1. Depend on it

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


dependencies:
  stream: ^2.2.1+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:stream/stream.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
66
Health:
Code health derived from static analysis. [more]
4
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
52
Learn more about scoring.

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

  • Dart: 2.7.0
  • pana: 0.13.1+4

Health suggestions

Fix lib/src/rspc/compiler.dart. (-44.93 points)

Analysis of lib/src/rspc/compiler.dart reported 119 hints, including:

line 6 col 1: Prefer using /// for doc comments.

line 30 col 59: Use = to separate a named parameter from its default value.

line 31 col 19: Use = to separate a named parameter from its default value.

line 31 col 43: Use = to separate a named parameter from its default value.

line 35 col 29: Unnecessary new keyword.

Fix lib/src/plugin/router.dart. (-33.04 points)

Analysis of lib/src/plugin/router.dart reported 80 hints, including:

line 6 col 1: Prefer using /// for doc comments.

line 10 col 3: Prefer using /// for doc comments.

line 19 col 48: Use = to separate a named parameter from its default value.

line 20 col 3: Prefer using /// for doc comments.

line 28 col 64: Use = to separate a named parameter from its default value.

Fix lib/src/rspc/tag.dart. (-28.53 points)

Analysis of lib/src/rspc/tag.dart reported 67 hints, including:

line 6 col 1: Prefer using /// for doc comments.

line 11 col 3: Prefer using /// for doc comments.

line 18 col 3: Prefer using /// for doc comments.

line 62 col 7: DO use curly braces for all flow control structures.

line 71 col 1: Prefer using /// for doc comments.

Fix additional 15 files with analysis or formatting issues. (-171.58 points)

Additional issues in the following files:

  • lib/src/server_impl.dart (60 hints)
  • lib/src/server.dart (46 hints)
  • lib/src/plugin/loader.dart (45 hints)
  • lib/src/connect_impl.dart (39 hints)
  • lib/src/rspc/build.dart (36 hints)
  • lib/src/rspc/tag_util.dart (36 hints)
  • lib/src/connect.dart (35 hints)
  • lib/src/plugin/loader_impl.dart (32 hints)
  • lib/src/rsp_util.dart (22 hints)
  • lib/src/rspc/main.dart (13 hints)
  • lib/proxy.dart (10 hints)
  • lib/plugin.dart (1 hint)
  • lib/rspc.dart (1 hint)
  • lib/stream.dart (1 hint)
  • bin/rspc.dart (Run dartfmt to format bin/rspc.dart.)

Maintenance suggestions

Documentation URL is insecure. (-5 points)

Update the documentation field and use a secure (https) URL.

Homepage URL is insecure. (-5 points)

Update the homepage field and use a secure (https) URL.

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and stream.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
args >=0.13.0 <2.0.0 1.5.2
charcode >=1.1.0 <2.0.0 1.1.2
http >=0.11.0 <2.0.0 0.12.0+2
logging >=0.11.0 <2.0.0 0.11.3+2
path >=1.3.0 <2.0.0 1.6.4
rikulo_commons >=3.0.0 <5.0.0 4.0.1
Transitive dependencies
async 2.4.0
collection 1.14.12
http_parser 3.1.3
meta 1.1.8
mime 0.9.6+3
pedantic 1.9.0
source_span 1.5.5
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6