README.md

kraftfahrstrasse - TypeScript WAMP client library for node/browsers

Introduction

kraftfahrstrasse is another WAMP implementation, which is fully driven by Typescript. This introduces type safety to the WAMP universe for the first time. We are very proud, we did this. We also used the newest language features, which mades the code more readable and better to maintain. So, keep in mind, that shipping to ES5 is not intended to work. We never tested that and we don't want to. Our applications, which depend on kraftfahrstrasse ship ES6 and it works fine.

We also want to keep the bundle size as low as possible, which is made possible by shipping ES6 modules and rely on ES6 tree shaking. We have dependencies like msgpack5 and ws which are installed but don't used until you import the modules. This results in a much smaller bundle size. We aim for a bundle size of 50kB, which is 5x smaller than autobahn-js.

This is the reason why our configuration seems a bit messy. You need to import the transport, serializer and authentication provider into your main file before you can use it. If you import them, Webpack 4 will include them into your bundle, if not, it wont. This is a huge advantage for your bundle size.

Design goals

• Fast
• Feature complete
• Clean and concise usage (i.e. no polymorphic callbacks)
• Simple configuration
• Full static type safety
• Best interopability with autobahnkreuz and the service libraries, to provide a seamless WAMP experience

Usage Example

The example below is intended to be run in node, if you'd like to run it in the browser change NodeWebSocketTransport to BrowserWebSocketTransport.

/*
First of all, import all required classes.
You're always going to need the Connection, a serializer and a transport.
For servers which require authentication, an AuthProvider is required.
*/
import {
  AnonymousAuthProvider,
  Connection,
  JSONSerializer,
  NodeWebSocketTransport,
} from '@verkehrsministerium/kraftfahrstrasse';

// Create a new connection object, using the parameters below.
const connection = new Connection({
  endpoint: "ws://localhost:4000", // Provide your broker URL here
  realm: "realm01", // Your realm.

  // The serializer you choose here impacts the handshake performed 
  // with the server, and is fixed during the lifetime 
  // of the connection. 
  // Typically, you would use JSON or MSGPack.
  // Provide an **instance** of a ISerializer here.
  serializer: new JSONSerializer(),
  
  // The transport you choose here selects the way how messages are 
  // sent to the server. 
  // You want to use a WebSocket transport here.
  // Provide a **factory** of a ITransport (ITransportFactory)
  transport: NodeWebSocketTransport, 

  transportOptions: {
    // Additional options passed directly into the transport constructor.
    // Documentation can be found in the documentation of the transport factories
  },

  // This class defines how the handshake with the server works.
  // It is used to provide a username, the authentication method 
  // and,optionally, more details like a password.
  // Pass an **instance** of a IAuthProvider to authenticate
  authProvider: new AnonymousAuthProvider(), 

  // Optionally, pass a function used to debug kraftfahrstrasse
  logFunction: console.log as any, 
});

const main = async () => {
  // wait until the connection is opened, after this point,
  // you may use .Call, .Register, .Subscribe, .Publish,
  // .CancelCall of the connection object.
  await connection.Open(); 
  
  // Example on how to subscribe to a topic
  const sub = await connection.Subscribe(
    "com.example.topic", // Topic
    (args, kwargs, details) => { // Event Handler
      console.log("Subscription:", args, kwargs, details);
    },
    {} // Advanced subscribe options, optional
  );

  // To unsubscribe, use:
  await sub.Unsubscribe();

  // Example on how to publish to a topic
  const pub = await connection.Publish(
    "com.example.topic", // Topic
    ["Hello World"], // Positional Arguments
    {}, // Keyword Arguments (optional)
    { // Advanced options (optional)
      // Request an answer from the router when
      // the publication has been delivered.
      "acknowledge": true, 
      // ...
    }
  );
  const id = await pub.OnPublished();
  console.log('Published event as', id);

  // Register a procedure
  const reg = await connection.Register(
    "com.example.rpc", // Function name
    async (args, kwargs, details) => { // Handler (asynchronous!)
      console.log('Got invoked:', args, kwargs, details);

      // Handlers can also return values.
      return {
        args,
        kwargs,
      };
    },
    {} // Advanced registration options.
  );

  // And unregister:
  await reg.Unregister();

  // Call a remote procedure
  // A call returns **TWO** values:
  // A promise of the call result, and its ID.
  // You can use the Call ID to cancel the call, when the router
  // supports call cancelation.
  const call = connection.Call(
    "com.example.rpc", // Function name
    ["Hello, World"], // Positional Arguments
    {}, // Keyword Arguments
    {}, // Advanced options.
  );

  // So to get the call result:
  const result = await call[0];
  console.log('Got call result:', result);

  // To cancel the running call:
  await connection.CancelCall(result[1], 'kill');
}
await main();

Configuration

Parameter	Type	Description
endpoint	string	endpoint describes the URL of your router.
realm	string	realm describes the realm, which should the client use.
transport	ITransport	transport describes a class, which is used to transport the data. WAMP supports multiple ways to connect to the router. Common transports are BrowserWebSocketTransport or NodeWebSocketTransport. Make sure, you import them correctly.
serializer	ISerializer	serializer describes an instance of ISerializer, which is used to serialize the protocol data for transport. Common serializers are JSON and MsgPack. Make sure, you import them correctly.
authProvider	IAuthProvider	authProvider describes an instance of IAuthProvider, which is supposed to handle the authentication to the router. Common authProvider are Anonymous and Ticket or resume token.
logFunction	logFunction?	Pass a custom function to include the output of kraftfahrstrasse into your own log management or log style.

Transports

At the moment, we only offer WebSocket based transports. We have one transport for nodejs (using the ws library) and another transport for browsers, using the native WebSocket object. HTTP LongPoll and rawsocket transports may be implemented against this interface, however we feel like most people focus on WebSocket transports. In the sections of the transports, the possible options are described.

BrowserWebSocketTransport

No further configuration is supported in a browser context.

NodeWebSocketTransport

The NodeWebSocketTransport uses the ws library under the hood, so head over to their documentation for an up-to-date list of configuration options. The transportOptions dict will be passed directly as options argument into the ws constructor.

Typically, you would like to set a custom CA, client certificates for TLS Authentication or connect timeout here.

Serializers

At the moment, we offer a JSONSerializer which is portable across node and the browser, as well as a portable MSGPack serializer, which relies on msgpack5. Both serializers confirm to the WAMP spec, however we provide the possibility to extend or write a custom serializer.

JSONSerializer

This serializer uses the JSON object present in nodeJS and modern browsers to encode and decode json. It follows the WAMP specification for binary message handling.

The subprotocol for the json serializer is: wamp.2.json.

BrowserMSGPackSerialzer/NodeMSGPackSerializer

This serializer uses msgpack5 to provide a more space-efficient serialization. It uses the wamp.2.msgpack subprotocol.

Attention: This serializer handles binary data as an extension to allow de-/reencoding of binary data at the server side to JSON. It is therefore NOT compatible with the crossbar.io router. If you absolutely need binary data, you can write your own msgpack serializer which is compatible with crossbar.io.

Authentication

WAMP offers different authentication methods, we honor this fact by providing a simple interface which allows us to extend and customize the authentication process.

WAMP distinguishes between transport level and protocol level authentication, with transport level being TLS Client Authentication, Cookie Authentication or Anonymous. Transport level authentications don't involve the calculation or presence of a shared secret or challenge/response at protocol level but instead rely on the transport below the protocol to handle this.

AnonymousAuthProvider

AnonymousAuthProvider represents the anonymous authentication method, it allows the user to specify a username (with a fallback on anonymous if none is provided).

TicketAuthProvider

TicketAuthProvider represents the ticket authentication method, using a shared secret to authenticate. TicketAuthProviders are used when using kraftfahrstrasse along with autobahnkreuz to authenticate users.

When using the TicketAuthProvider, the password will not be stored within the AuthProvider, but instead the AuthProvider calls a user defined function to calculate the ticket based on the server issued details object.

CookieAuthProvider

The CookieAuthProvider is a transport-level authentication provider, which means that this connection is identified by the client who presented cookies at the connection establishment procedure. No further configuration is required.

TLSAuthProvider

The TLSAuthProvider is a transport-level authentication provider, which means that this connection is identified by the client who presented a TLS client certificate at the connection establishment procedure. No further configuration is required.

We recommend using the TLSAuthProvider for backend components.