nexus

module
v3.0.0-...-7d4fba5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 27, 2023 License: MIT

README

WAMP v2 router library, client library and router service

Build Status License GoDoc

nexus is a WAMP v2 router library, client library, and a router service, that implements most of the features defined in the WAMP-protocol advanced profile. The nexus project is written in Go and designed for highly concurrent asynchronous I/O. The nexus router provides extended functionality. The router and client interoperate with other WAMP implementations.

Documentation

See the nexus project Wiki for documentation, examples, and operational details.

GoDoc for API documentation.

What is WAMP and nexus

The Web Application Messaging Protocol (WAMP) is an open standard WebSocket subprotocol that provides two application messaging patterns in one unified protocol: Remote Procedure Calls and Publish & Subscribe. WAMP is also referred to as WAMP-proto it distinguish it from [other uses](https://en.wikipedia.org/wiki/WAMP_(disambiguation) of the acronym.

Using WAMP you can build distributed systems out of application components which are loosely coupled and communicate in (soft) real-time.

Nexus is a software package that provides a WAMP router library, client library, and stand-alone WAMP router service. This nexus package provides a messaging system for building distributed applications and services. Endpoints using websockets, TCP sockets, Unix sockets, and in-process connections may all communicate with each other via pub/sub and routed RPC messaging.

  • The router library can be used to build custom WAMP routers or to embed a WAMP router in an application.
  • The client library can be used to build clients that connect to any WAMP server, or to communicate in-process with a WAMP router embedded in the same application.
  • The router service can be run as-is to provide WAMP routing.

Installation

Install nexusd router service from source
go get -d github.com/dtegapp/nexus/nexusd
cd ${GOPATH}/src/github.com/dtegapp/nexus/nexusd
make install

Run nexusd -help to see usage information. Although nexusd can be run using only command line flags, a configuration file offers much more configurability.

Create configuration file and run nexusd service
cp ${GOPATH}/src/github.com/dtegapp/nexus/nexusd/etc/nexus.json ./
vi nexus.json
nexusd -c nexus.json
Install examples to run and test with
git clone git@github.com:dtegapp/nexus.git
cd nexus/examples

Building routers and clients with nexus

The nexus router library is used to build a WAMP router or embed one in your service. The nexus client library is used to build WAMP clients into you goloang applications. To use either of these libraries, import the v3 version of the appropriate packages. Version v3 is the only currently supported version.

import (
	"github.com/dtegapp/nexus/v3/client"
	"github.com/dtegapp/nexus/v3/wamp"
)

Run nexusd from a container

Pull the nexusd container image built with the latest code version and run the container:

docker pull ghcr.io/dtegapp/nexusd:latest
docker run ghcr.io/dtegapp/nexusd:latest

Now it just works. By default, the router accepts connections on port 8080 and allows anonymous communication with clients using realm1. You can change the values or get help by passing options to the container process:

docker run ghcr.io/dtegapp/nexusd:latest --ws 0.0.0.0:8888 --realm autobahn
docker run ghcr.io/dtegapp/nexusd:latest --help

Alternatively, you can mount the nexusd configuration file to the container, and get a more customizable and secure environment. See the nexusd configuration reference for details. Finally, you can also run the container process as an unprivileged user.

Examples

Look at the examples to see how to create simple clients and servers. Follow the README.md in the nexus/examples directory. Examples of using advanced profile features are also available in the wiki documentation.

https://github.com/dtegapp/nexus/tree/v3/examples

The examples include interoperability examples to demonstrate nexus working with different WAMP implementations. Each of these has its own README.md that describes how to set up the environment and run the examples.

https://github.com/dtegapp/nexus/tree/v3/examples/interop

The nexusd service is also an example stand-alone WAMP router. All the router options are configurable in nexusd using a configuration file, and one is provided in the nexusd/etc/ directory. This can be used as starting point to write your own WAMP router service.

https://github.com/dtegapp/nexus/tree/v3/nexusd

Contributing

Please read the Contributing guide if you are interested in becoming a contributor to this project.

Please report any problems, or request changes and new functionality by opening an issue.

Nexus Features

  • Concurrent Asynchronous I/O Nexus supports large numbers of clients concurrently sending and receiving messages, and never blocks on I/O, even if a client becomes unresponsive. See Router Concurrency and Client Concurrency for details.
  • WAMP Advanced Profile Features This project implements most of the advanced profile features in WAMP v2. See current feature support provided by nexus. Nexus also offers extended functionality for retrieving session information and for message filtering, giving clients more ability to decide where to send messages.
  • Flexibility Multiple transports and serialization options are supported, and more are being developed to maximize interoperability. Currently, nexus provides websocket, rawsocket (tcp and unix), and local (in-process) transports. JSON, MessagePack, and CBOR serialization is available over websockets and rawsockets.
  • Security TLS is available over websockets and rawsockets with client and server APIs that allow configuration of TLS. The nexus router library also provides interfaces for integration of client authentication and authorization logic.
Status

The currently maintained version of this module is 3.x. Earlier major versions are no longer supported.

Advanced Profile Feature Support

RPC Features
Feature Supported
progressive_call_results Yes
progressive_call_invocations Yes
call_timeout Yes
call_canceling Yes
caller_identification Yes
call_trustlevels No
registration_meta_events Yes
registration_meta_procedures Yes
pattern_based_registration Yes
shared_registration Yes
sharded_registration No
registration_revocation No
procedure_reflection No
payload_passthru_mode Yes
PubSub Features
Feature Supported
subscriber_blackwhite_listing Yes
publisher_exclusion Yes
publisher_identification Yes
publication_trustlevels No
subscription_meta_events Yes
subscription_meta_procedures Yes
pattern_based_subscription Yes
sharded_subscription No
event_history Yes
topic_reflection No
testament_meta_api Yes
payload_passthru_mode Yes
Other Advanced Features
Feature Supported
rawsocket (TCP & Unix) transport Yes
session meta events Yes
session meta procedures Yes
TLS for websockets Yes
TLS for rawsockets Yes
challenge-response authentication Yes
cookie authentication Yes
ticket authentication Yes
batched WS transport No
longpoll transport No
websocket compression Yes

Extended Functionality

Nexus provides extended functionality around subscriber black/white listing and in the information available via the session meta API. This enhances the ability of clients to make decisions about message recipients.

Directories

Path Synopsis
Package AAT is a collection of Automated Acceptance Tests.
Package AAT is a collection of Automated Acceptance Tests.
Package client provides a WAMP client implementation that is interoperable with any standard WAMP router and is capable of using all of the advanced profile features supported by the nexus WAMP router.
Package client provides a WAMP client implementation that is interoperable with any standard WAMP router and is capable of using all of the advanced profile features supported by the nexus WAMP router.
examples
interop/autobahn-python
Go WAMP client: publisher and caller
Go WAMP client: publisher and caller
newclient
Package newclient provides a function to create a new client with the socket type and serialization specified by command like arguments.
Package newclient provides a function to create a new client with the socket type and serialization specified by command like arguments.
rpc_progressive_results/caller
Progressive Call Results Example Caller
Progressive Call Results Example Caller
server
Example nexus WAMP router that handles websockets (with/out TLS), TCP rawsockets (with/out TLS), and unix rawsockets.
Example nexus WAMP router that handles websockets (with/out TLS), TCP rawsockets (with/out TLS), and unix rawsockets.
simple
Simple example nexus WAMP router that handles websockets.
Simple example nexus WAMP router that handles websockets.
Package main implements a stand-alone nexus router service.
Package main implements a stand-alone nexus router service.
Package router provides a WAMP router implementation that supports most of the WAMP advanced profile, offers multiple transports and TLS, and extends publication filtering functionality.
Package router provides a WAMP router implementation that supports most of the WAMP advanced profile, offers multiple transports and TLS, and extends publication filtering functionality.
auth
Package auth provides interfaces for implementing authentication logic that the WAMP router can use.
Package auth provides interfaces for implementing authentication logic that the WAMP router can use.
Package stdlog provides a minimal logging interface to allow nexus to use nearly any logging implementation.
Package stdlog provides a minimal logging interface to allow nexus to use nearly any logging implementation.
Package transport provides a websocket, rawsocket, and local transport implementation.
Package transport provides a websocket, rawsocket, and local transport implementation.
serialize
Package serialize provides a Serializer interface with implementations that encode and decode message data in various ways.
Package serialize provides a Serializer interface with implementations that encode and decode message data in various ways.
Package wamp defines all message types, data types, and reserved URI values defined by the WAMP specification.
Package wamp defines all message types, data types, and reserved URI values defined by the WAMP specification.
crsign
Package crsign provides functionality for signing challenge data in challenge-response authentication.
Package crsign provides functionality for signing challenge data in challenge-response authentication.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL