Xbus

Build Status License

Xbus provides high-level application messaging on top of NATS.

Requirements

Golang

This is a Go project.

Versions of Go we test:

  • 1.8
  • Version 1.7 may enough but we do not build or test with it, so it may break anytime.

Govendor

We use govendor as our vendoring tool, you must have it installed in your system (or local tools) to be able to reproduce a correct build of Xbus.

Postgresql

Xbus uses a postgresql database 9.5+ to serialize configuration and events.

Build

Build as a regular Go package:

govendor sync
make install

Running

3 binaries are created:

  • xbusd: Main Xbus program.
  • xbusctl: Xbus administration program (ctl = “control”); remotely connects to xbusd.
  • xbus-client: Administration of actors (programs that can connect to Xbus).

Each program may be run with --help to see available commands / flags / etc.

Warning: xbusd <xbusd> can produce a LOT of logs when placed under load. The server will crash if it is unable to write to stdio/stderr. Init systems that implement rate limitation for logs (such as systemd) may cause xbusd <xbus> to crash if the server exceeds this limit.

Updating

  • The migration directory contains scripts one can use to migrate Xbus databases from one version to the other.

Versions

3.0.0-beta.14 (2018-11-13)

Note

This is the last version for which a SQL script has to be applied manually. Once done, run xbusd migrate to finalize the database migration.

  • [ci] Upgrade go to 1.11

  • xbusd migrate: new command that takes care of updating the database.

  • Add certificate renewal tooling:

    • (xbusctl|xbusd) account reset-cert
    • (xbus-client|xbusctl) renew-cert

3.0.0-beta.13 (2018-10-30)

  • xbusd:
    • Implements process cancel (#27)
  • xbusctl:
    • ps display the graph name & version, and the emitter name instead of their ids
    • Fix a crash on ‘ps pause’ and other ‘ps’ subcommands (#124)
    • Add the command ps cancel for canceling processes (#27)
  • doc:
    • Embed a basic documentation of the API

3.0.0-beta.12 (2018-10-22)

Note

This version is NOT protocol compatible with former versions of xbus. xbusd and the clients must all be upgraded simultaneously.

  • features:
    • Store configuration entries on the actor definitions in the server. This allow external tools like xbus-http to remain stateless apps by storing a few configuration entries on the actors.
  • xbusd:
    • Implements the new Process.ExportStream api endpoint
    • Implements the new Storage.ActorLeaving api endpoint
    • Implements the new Online/Unresponsive properties of Actor
    • As part of the actor protocol refactoring: - Implements the new Director service - Implements the new EnvelopeStorage service - Drop the emission micro-service
    • Gracefully handle broker overflow (#41)
    • A gateway account can now login for itself, getting access to the actor definitions.
    • A gateway account can now login as an actor without extra credentials.
    • service register: Invalid account names are now rejected (#118)
  • xbusctl:
    • register now gives the actual xbusd command to run to complete the registration
    • ps export
      • is not size-limited anymore.
      • added --export-envelope to enable envelope export
      • added --export-envelope-size-limit to limit envelope export size
    • ps pause|resume now takes the same filtering options as the other ps commands.
    • Add the account get-apikey and account set-apikey commands (#101)
    • Add the envelope get command (#96)
    • graph query is now graph list for consistency purpose.
  • xbus-client:
    • register now gives the actual xbusctl command to run to complete the registration
  • Merge xbus-http into the xbus project. The http gateway is becoming an official part of xbus.
  • Introduce a new tool, Xbus Fullenv. It is meant to set up and pilot test environments of xbus from a single configuration file.

3.0.0-beta.11 (2018-04-13)

Note

This version is NOT protocol compatible with former versions of xbus. xbusd and the clients must all be upgraded simultaneously.

  • Reimplement all the NATS calls and handlers with nrpc and the xbus-api proto files.
  • Expose prometheus metrics of the API
  • Implement ‘xbusctl graph get’
  • When –config is used, log an error if the configuration file is not found.
  • Fix: In some case (especially when xbus-http is involved), the emission service would deadlock itself.
  • Fix: Server crashed at startup if sentry was enabled.
  • Fix: Purges would timeout with big volumes of process or envelopes.
  • Optimization: Add indexes to item and log_entry tables. This fix performances issues with big envelopes.
  • Update gnatsd to 1.0.4
  • Switch to go 1.8
  • Cleanups
  • ci: provides automatically built packages and docker files
  • Fix: A ‘active’ graph that is invalid could not be deactivated.

3.0.0-beta.10 (2017-10-19)

  • Fix 3.0.0-beta.9 migration script performances on medium to large databases.
  • Fix an issue when too many inputs or ouputs were defined on a graph node
  • Fix a deadlock in the emission service that can happen with big envelopes sent in many small envelopes with the right timing.
  • Improve process state management:
    • State update is now centralized in a dedicated routine, avoiding some possible race conditions.
    • If an error occurs during state update, the process status is now set in ‘error’.
    • When a process status is set to ‘error’, the reason is added to the process state.
  • xbusd:
    • Add a sentry.dsn setting to send errors to sentry
  • xbus-client:
    • Add a sentry.dsn setting

Database

  • Table graph_node:
    • Change column inputs type to TEXT
    • Change column outpus type to TEXT
  • Table process_log_entry:
    • Add column processing_error (BOOLEAN)
  • Table process_state:
    • Add column status_reason (TEXT)

3.0.0-beta.9 (2017-09-19)

  • solve issue #64 (connection errors when too many client connect at the same time)
  • switch to gnatsd 1.0.2
  • Implement the process ‘export’ and ‘purge’ APIs
  • Implement the new process filtering API
  • Track a few the process change timestamps
  • Implement the envelope and logs purge APIs
  • xbusd:
    • add ‘–gnatsd-http[s]-(host/port)’ flags for enabling gnatsd monitoring
    • cert generate: add a ‘–expire’ flag for certificate validity range
    • account accept: add a ‘–cert-expire’ flag for the account cert validity range
  • xbusctl:
    • ‘actor reject’ now accepts the same arguments as ‘actor accept’
    • Add the ‘ps export’ and ‘ps purge’ commands
    • Use the new process filtering API to improve the cli
    • Add the ‘envelope purge’ command
    • Add the ‘logs purge’ command
    • account accept: add a ‘–cert-expire’ flag for the account cert validity range

Database

  • Table process_state: - Add field status_changed - Add field nodes_state_changed - Add field pm_changed
  • Tables emission, process_log_entry, process_state, route: Add ON DELETE CASCADE to *_process_id_fkey foreign keys
  • Table route_target: Add ON DELETE CASCADE to route_target_route_id_fkey

3.0.0-beta.8 (2017-06-03)

  • Add a postmortem API, service and CLI. They allow to inspect and handle failed processes.
  • Add database connection limit parameter: database.max-connections
  • Add APIs and command line tools (:prog:`xbusctl pm <xbusctl>`) for handling processes with errors or warning after they ended.
  • Add full environment tests, allowing some tests not possible with fullstack_tests, like testing the cli tools, testing random server crashes…
  • Update the graph API implementation, following go-xbus/api changes
  • Make envelope reception more robuts (Issue #39). Some inconsistent states are not possible anymore.
  • Handle gateway authentication with api keys.
  • Fix all the deadlocks we found on heavy load.
  • graph validation: Now identify invalid emitter/consumer input/output, and sourcematch-less emitters.
  • xbusd:
    • ‘account accept/reject’ now takes id or name in addition to fingerprints
  • xbusctl:
    • Add ‘actor delete’
    • Fix ‘actor list’ filter handling
    • ‘actor accept/reject’ now takes a name or id
    • Add ‘account delete’
    • Refactor ‘graph’ commands. The graph source file is now never updated by the command, and the name, version and status are updated by command line actions and arguments, not in the source file.
  • [doc] Document the “processing end” message in the connector API doc.
  • [doc] Fix minor issues in the connector API doc.

Database

  • Table process_state: - Add field pm_level varchar(255) - Add field pm_status varchar(255) - Add field pm_comment varchar(255)

Notice

  • A backwards incompatible change has been introduced in the configuration: database becomes database.dsn, the cli flag database becomes database-dns. Refer to the sample file etc/xbusd_sample.yaml.

3.0.0-beta.7 (2017-03-09)

  • Add support for fragmented envelopes, which implies a lot of code cleaning and a few refactoring.
  • Add a route cache
  • Reduce broker/emission coupling

Database

  • Now requires Postgresql >= 9.5
  • New Table: route
  • New Table: route_target

3.0.0-beta.6 (2017-02-03)

  • [doc] Update Quickstart to match latest go-xbus demo.relay settings
  • [auth] Remove debug log when a client is authenticated
  • Switch to go-xbus 3.0.0-beta.6
  • Fix a host / port parsing issue that was preventing the nats-host setting from being set to 0.0.0.0.

3.0.0-beta.5 (2017-01-26)

  • Switch to go-xbus 3.0.0-beta.5
  • Fix: graph validation error message for invalid edges were wrong (‘origin’ was switched with ‘destination’.
  • Doc: Add a fully fonctionnal graph to the Quickstart section, making it a complete and running example of a bus.

API

  • New: Graph nodes how have a actors attribute, which references actors by name or id. The actorids attribute is deprecated.
  • Fix: In case no graph matches a new envelope, a ack error is returned to the emitter.

Database

  • New: Table graph_node: add field actors varchar(255)

CLI

  • xbusd: Allow custom hostdefs for server CA
  • xbus-client: Embed demo actors from go-xbus/demo

3.0.0-beta.4 (2017-01-20)

  • Build releases binaries from the right changeset.
  • Extract reusable parts of this program to go-xbus.
  • Switch to go-xbus 3.0.0-beta.4

3.0.0-beta.3 (2017-01-13)

API

  • API Break: Add the “ActorProcessingEnd” entry point. It must be called by consumers to signal processing success or failure, and by other actors for processing errors. It adds support for long-running processing by consumers without hitting transfert timeout.
  • API Beak: Rename ActorType to ActorKind, and all ‘Type’ fields of type ActorType to ‘Kind’.
  • API Addition: Add a logging API for actors.

Database

  • Provides a SQL migration script, that does: - actor table: Drop unique index (name / type). - actor table: Add a unique index (name). - actor table: Rename type to kind. - emission table: event_positions type changed to TEXT (was VARCHAR(255)) - New log_entry table that stores log messages.

Other

  • Gnatsd: switch to upstream version (which merged our TLS auth related patch)
  • Better test coverage
  • More graph examples in the graph doc
  • Graph validation: Check for invalid or duplicate node ids
  • xbus-client: Better behavior when configuration file is missing
  • make xbus-client/cmd extendable
  • client: Add apis to easily start a group of actors from a configuration file

3.0.0-beta.2 (2016-12-22)

  • Graph validation. When pushing a graph, a list of validation errors (if any) will be returned and displayed. A non-valid graph cannot be published, preventing many common mistakes that would be otherwise hard to detect.
  • Optionnally capture SQL logs (see xbusd serve options –debug-sql-queries and –debug-sql-bindings)
  • Embed detailed version information in the binaries (try –version and –full-version flags on the binaries)
  • Upgrade gnatsd embedded version
  • Build static binaries
  • Embed documentation in the distribution package
  • Documentation fixes
  • A few logging level changes

3.0.0-beta.1 (2016-12-12)

Initial release. It features:

  • Handling of simple envelopes
  • Graphs
  • Process
  • Account/actors management
  • …