Xbus¶
Xbus provides high-level application messaging on top of NATS.
Requirements¶
Postgresql¶
Xbus uses a postgresql database 9.5+ to serialize configuration and events.
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.1 (2019-06-19)¶
- actor deletion is no longer blocked if some logs refer to it
- envelope purge is no longer blocked if some logs refer to it
- account deletion: related actors are also deleted after user confirmation
- small documentation changes
- pipelines (and process): consumers can be matched by name or id and not only by roles.
- log an error when an actor is marked offline after not responding
- xbusd-enterprise & xbusd-lts: fix an excessive CPU usage.
- xbusctl:
- actor list now display the name of the account of each actor
- account: add a ‘export’ command to recreate a client configuration file.
- ps export: fix exporting huge list of process (10th of thousands)
- xbus-http: add the ‘renew-cert’ command
- ‘renew-cert’ command:
- print an error if reset-cert was not applied to the account prior to the cert renewal.
3.0.0 (2019-03-26)¶
- service envelopestorage: raise slow emitter detection delay from 15 to 30 seconds.
- sentry: report failed Process to sentry
- xbusd: new setting “sentry.environment”
3.0.0-rc.6 (2019-02-15)¶
API:
- ProcessState.Envelope now returns a single Process
- ProcessState.Envelope subject: emitter is now a method param
Those changes reflects the fact that a single envelope should never trigger several _concurrent_ processes.
3.0.0-rc.5 (2019-02-01)¶
Warning
All the NATS subject of the API are now prefixed with “xbus.default” instead of just “xbus”, which breaks the API. Xbusd, xbus-http, xbusctl and _all_ the clients must be upgraded at the same time.
It also impacts hand-written clients that need to adjust the subject they use.
- xbusctl: Fix ‘xbusctl pm’ timeout on big lists.
- xbusd: Fix pipeline saving to forbid non-draft pipeline update.
- xbusd: Fix a crash after 1000 process on one actor through xbus-http /processrequest (#159).
xbusd --version
now ignores completly the configuration and the ‘certs’ directory (#160).
3.0.0-rc.4 (2019-01-22)¶
- xbusd cert generate: improve –host-defs documentation
- xbus-fullenv: extend variable substitution to client fullenv-specific settings
- xbusd: fix pipeline matching by actor/roles (#155)
- xbusd: fix service ‘control’ stall if a ps export is canceled (#157)
- xbusd: service ‘control’ process functions use a worker pool, enabling parallel executions of ‘xbusctl ps’ commands.
- xbusd: fix help of the ‘–config’ flag (#115)
- xbus-http: implements auto-reconnection of webhooks (#153)
- xbusctl: ps export: add a “–quiet” flag to disable extra logging (#144)
3.0.0-rc.3 (2019-01-07)¶
- database: remove actor.config size limit.
- xbusd: adjust control.Process.Query batch size to avoid too big fragments (see #142).
- xbus-http: fix webhooks response handling (see #139, #140 and #141)
3.0.0-rc.2 (2018-12-27)¶
- xbus-fullenv: add a ‘–var’ flag to do variable substitution in the configuration file.
- documentation: Add a ‘migration’ section
- Enforce client protocol version compatibility: a client must advertise its protocol version when connecting, and will fail to authenticate if the version is not present or is not compatible with the server protocol version.
- Add link options for producing licensed binaries.
- Remove some ci files
- Add json support to the WhoAmI service
3.0.0-rc.1 (2018-12-14)¶
- fix the 3.0.0-beta.14 migration script
- The client configuration are not rewritten at ‘register’ anymore. The TLS entries are written to one or several separate files instead.
- The client ‘actors’ configuration entry now accepts actor names as keys instead of integer values
- http: Fix an issue with enveloppe/process polling returning the same value several times (see #133)
- update most of the dependencies (see #134)
- xbusd: The default ‘cert-dir’ is now relative to the configuration file instead of the current directory.
3.0.0-beta.16 (2018-12-03)¶
Base the xbus-fullenv docker image on busybox
Fix the certificate renewal tests
Detect stalled envelope emissions and cancel the process accordingly
xbus-fullenv run
:- Add the
--auto-startup
flag - Add the
--batch
flag
- Add the
3.0.0-beta.15 (2018-11-19)¶
- Renamed ‘graph’ to ‘pipeline’ in CLI and API
xbusctl
- Fix configuration by environment variable
ps export
: Add--export-jobs
flagps
: Add--pipeline
flag to filter by pipeline
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 registrationps 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
andaccount set-apikey
commands (#101) - Add the
envelope get
command (#96) graph query
is nowgraph 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
- Add a
- xbus-client:
- Add a
sentry.dsn
setting
- Add a
Database¶
- Table
graph_node
:- Change column
inputs
type toTEXT
- Change column
outpus
type toTEXT
- Change column
- Table
process_log_entry
:- Add column
processing_error
(BOOLEAN
)
- Add column
- Table
process_state
:- Add column
status_reason
(TEXT
)
- Add column
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 fieldstatus_changed
- Add fieldnodes_state_changed
- Add fieldpm_changed
- Tables
emission
,process_log_entry
,process_state
,route
: AddON DELETE CASCADE
to*_process_id_fkey
foreign keys - Table
route_target
: AddON DELETE CASCADE
toroute_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 fieldpm_level varchar(255)
- Add fieldpm_status varchar(255)
- Add fieldpm_comment varchar(255)
Notice¶
- A backwards incompatible change has been introduced in the configuration:
database
becomesdatabase.dsn
, the cli flagdatabase
becomesdatabase-dns
. Refer to the sample fileetc/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 to0.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. Theactorids
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 fieldactors 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: Renametype
tokind
. -emission
table:event_positions
type changed toTEXT
(wasVARCHAR(255)
) - Newlog_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
- …