connectanum 1.0.0-dev.8

  • Readme
  • Changelog
  • Example
  • Installing
  • 69

connectanum-dart #

This is a WAMP client implementation for the dart language and flutter projects. The projects aims to provide a simple and extensible structure that is easy to use. With this project I want return something to the great WAMP-Protocol community.

WAMP is trademark of Crossbar.io Technologies GmbH.

TODOs #

  • add code coverage report
  • add github runners to test code with multiple dart versions
  • Multithreading for callee invocations
    • callee interrupt thread on incoming cancellations
  • better docs
  • msgpack serializer
  • get the auth id that called a method
  • handle ping pong times
  • auto reconnect handling, but keep abstract socket interface
    • difference between intentionally and unintentionally disconnect
    • websocket has error and regular close event. use them if possible or use close with internal state from this package?

Supported WAMP features #

Authentication #

Advanced RPC features #

  • ☑ Progressive Call Results
  • ☑ Progressive Calls
  • ⬜ Call Timeouts
  • ☑ Call Canceling
  • ☑ Caller Identification
  • ⬜ Call Trust Levels
  • ☑ Shared Registration
  • ⬜ Sharded Registration

Advanced PUB/SUB features #

  • ☑ Subscriber Black- and Whitelisting
  • ☑ Publisher Exclusion
  • ☑ Publisher Identification
  • ⬜ Publication Trust Levels
  • ☑ Pattern-based Subscriptions
  • ⬜ Sharded Subscriptions
  • ⬜ Subscription Revocation

Stream model #

The transport contains an incoming stream that is usually a single subscribe stream. A session will internally open a new broadcast stream as soon as the authentication process is successful. The transport stream subscription passes all incoming messages to the broad cast stream. If the transport stream is done, the broadcast stream will close as well. The broad cast stream is used to handle all session methods. The user will never touch the transport stream directly.

Start the client #

To start a client you need to choose a transport module and connect it to the desired endpoint. When the connection has been established you can start to negotiate a client session by calling the client.connect() method from the client instance. On success the client will return a session object.

If your transport disconnects the session will invalidate. If a reconnect is configured, the session will try to authenticate an revalidate the session again. All subscriptions and registrations will be recovered if possible.

import 'package:connectanum/connectanum.dart';
import 'package:connectanum/json.dart';

final client = Client(
  realm: "my.realm",
  transport: WebSocketTransport(
    "ws://localhost:8080/wamp",
    new Serializer(),
    WebSocketSerialization.SERIALIZATION_JSON
  )
);
final session = await client.connect();

RPC #

to work with RPCs you need to have an established session.

import 'package:connectanum/connectanum.dart';
import 'package:connectanum/json.dart';

final client = Client(
  realm: "my.realm",
  transport: WebSocketTransport(
    "ws://localhost:8080/wamp",
    new Serializer(),
    WebSocketSerialization.SERIALIZATION_JSON
  )
);
final session = await client.connect();

// Register a procedure
final registered = await session.register("my.procedure");
registered.onInvoke((invocation) {
  // to something with the invocation
})

// Call a procedure
await for (final result in session.call("my.procedure")) {
  // do something with the result
}

1.0.0-dev.8 #

  • added session close
  • fixed serializer to handle incoming abort messages and serialize outgoing auth details
  • added example code
  • fixed publish
  • added some missing tests

1.0.0-dev.7 #

  • better stub import for WebSocket transport
  • fixed SCRAM authentication

1.0.0-dev.6 #

  • fixed hello.details serialization code
  • added error in serializer for incoming messages
  • added serializer logging for wrong incoming messages
  • more cleanup code to meet pana analysis requirements

1.0.0-dev.5 #

  • more cleanup code to meet pana analysis requirements

1.0.0-dev.4 #

  • more cleanup code to meet pana analysis requirements
  • added a working unit test for websocket transport in the vm

1.0.0-dev.3 #

  • more cleanup code to meet pana analysis requirements

1.0.0-dev.2 #

  • cleanup code to meet pana analysis requirements

1.0.0-dev.1 #

example/main.dart

import 'package:connectanum/connectanum.dart';
import 'package:connectanum/json.dart';

void main() async {
  // Start a client that connects without the usage of an authentication process
  final client1 = Client(
      // The realm to connect to
      realm: "demo.connectanum.receive",
      // We choose WebSocket transport
      transport: WebSocketTransport(
        "wss://www.connectanum.com/wamp",
        new Serializer(),
        WebSocketSerialization.SERIALIZATION_JSON,
      ));
  Session session1;
  try {
    // connect to the router and start the wamp layer
    session1 = await client1.connect();
    // register a method that may be called by other clients
    final registered = await session1.register("demo.get.version");
    registered
        .onInvoke((invocation) => invocation.respondWith(arguments: ["1.1.0"]));
    // subscribe to a topic that my be published by other clients
    final subscription = await session1.subscribe("demo.push");
    subscription.eventStream.listen((event) => print(event.arguments[0]));
  } on Abort catch (abort) {
    // if the serve does not allow this client to receive a session
    // the server will cancel the initializing process with an abort
    print(abort.message.message);
  }

  final client2 = Client(
      realm: "demo.connectanum.receive",
      transport: WebSocketTransport(
        "wss://www.connectanum.com/wamp",
        new Serializer(),
        WebSocketSerialization.SERIALIZATION_JSON,
      ));
  try {
    final session2 = await client2.connect();
    // call session 1 registered method and print the result
    session2
        .call("demo.get.version")
        .listen((result) => print(result.arguments[0]));
    // push a message to session 1
    await session2.publish("demo.push", arguments: ["This is a push message"]);
    // close both clients after everything is done
    session1.close();
    session2.close();
  } on Abort catch (abort) {
    print(abort.message.message);
  }
}

Use this package as a library

1. Depend on it

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


dependencies:
  connectanum: ^1.0.0-dev.8

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

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

3. Import it

Now in your Dart code, you can use:


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

We analyzed this package on Jul 5, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Health suggestions

Fix lib/src/serializer/json/serializer.dart. (-1 points)

Analysis of lib/src/serializer/json/serializer.dart reported 2 hints:

line 48 col 19: This function has a return type of 'AbstractMessage', but doesn't end with a return statement.

line 345 col 42: Use isNotEmpty instead of length

Fix lib/src/protocol/session.dart. (-0.50 points)

Analysis of lib/src/protocol/session.dart reported 1 hint:

line 168 col 7: Future results in async function bodies must be awaited or marked unawaited using package:pedantic.

Maintenance suggestions

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.3.0 <3.0.0
logging ^0.11.4 0.11.4
pointycastle ^1.0.2 1.0.2
saslprep ^1.0.0 1.0.0
Transitive dependencies
unorm_dart 0.1.2
Dev dependencies
stream_channel 2.0.0
test ^1.12.0