diff options
author | Matthias Beyer <matthias.beyer@ifm.com> | 2022-07-15 17:36:23 +0200 |
---|---|---|
committer | Matthias Beyer <matthias.beyer@ifm.com> | 2022-08-30 13:52:36 +0200 |
commit | 08a32f3294d65b4011e54838fc67c792cf8f3ff0 (patch) | |
tree | 8360aa6821b7d1d5efe5b91c4089c9dc149e4a67 | |
parent | 49aac61a251a95db7bc8e8b3589caa1a99db682d (diff) | |
parent | 06d1f29576c52566bd3ea8715c02025832de06a6 (diff) |
Merge branch 'feature/add_tedge_api_impl' into integrate-feature-apiintegrate-feature-api
This merge now introduces the "core" library, a CLI implementation, a
helper library for simplifying some plugin implementation as well as a
number of example plugins.
The following message can help you understanding the ideas and concepts
that are introduced with this merge as well as help to answer some
questions that might arise when reviewing the changeset.
In the previous merge we introduced the API. This API does _only_ define
an interface how thin-edge.io plugins can be written in a way so they
can be used within the thin-edge.io ecosystem.
For more information, have a look at the merge commit where the API was
introduced.
This merge now introduces a list of crates of different importance. I
will quickly introduce them here, with only some short notes.
More is written in the `README.md` file of the respective crate.
* `tedge_core` - The implementation of the part of thin-edge.io, that
runs the plugins which implement the `tedge_api`
* Ensures composability via configuration with fail-early mechanisms
if configuration is faulty
* Runs plugins concurrently on multiple cores without spending much
time itself
* Implements high-performance asynchronous and typed message passing
without serialization/deserialization overhead
* Ensures plugin lifecycle with panic-catching in all phases of the
lifecycle of a plugin
* Features fine-grained `tracing` output to be able to make use of the
excellent `tracing` ecosystem and enabling detailed performance
analytics
* Ensures proper plugin shutdown in case of application shutdown
* If a plugin does not shutdown after a certain configurable
timeout, the plugin will be killed
* High testability! The core is tested for several things, for
example:
* whether a plugin does panic in any phase of it's lifecycle, so
that the core does not crash if it happens
* whether a plugin does shutdown cleanly
* whether application startup is aborted properly if plugins are
wired up that are not compatible (`Plugin A` wants to send
`Message M` to `Plugin B`, but `Plugin B` only supports `Message
X`)
* `tedge-cli` - one possible implementation of the CLI for starting a
thin-edge.io process. This implementation is not really big, which is
definitively intended
* Implements easy to use CLI interface
* Setup of stdout/chrome/Tracy tracing output
* Ties together the core and the plugins
* `tedge_lib` - A helper library for helping plugin authors with some
recurring aspects/patterns in a plugin implementation
* Mainloop abstraction helper for "ticking" mainloop
* Mainloop abstraction for stateful `loop{}`-style mainloops
* Defines common message types, e.g.:
* `Measurement` (just a mockup for now, details have to discussed
later)
* `Notification` (just a mockup for now, details have to discussed
later)
* Defines config helper types for more typing in the configuration
* Defines address helper types for more convenience over the basics of
message passing
* A list of example plugin implementations of different complexity
* `plugin_avg` - A plugin that calculates an average value from a
stream of measurements sent to it. This is a good example plugin for
learning how a plugin implementation could look like
* `plugin_log` - A plugin that logs all messages sent to it. This is
intentionally minimal and does not serve a real purpose
* `plugin_httpstop` - A plugin that tells thin-edge.io to stop if a
web request was made to a certain endpoint.
In short: `curl localhost:8080` to shutdown thin-edge.io. This would
also be a good example for reviewing how a basic plugin
implementation would look like
* `plugin_inotify` - A plugin that watches some files with inotify and
sends notification messages if inotify raises an event. This is a
good example of a bit more involved plugin
* `plugin_measurement_filter` - A plugin to filter `Measurement`
messages by a user-defined predicate. Think "Ignore all measurements
below value `12`"
* `plugin_mqtt` - A way for connecting thin-edge.io with an MQTT
broker. This plugin does not parse MQTT payloads, which is done by
another plugin, depending on the usecase that one wants to cover.
Instead it only contains the MQTT handling, so that other plugins do
not have to care about the transport mechanisms their payloads are
sent/received with
* `plugin_mqtt_measurement_bridge` - A plugin that receives
`Measurement` objects, serializes them to JSON and sends them to an
MQTT Plugin. This is another building block in an MQTT setup and
makes the serialization method decoupled from the business logic
that emits `Measurement` objects.
* `plugin_sysstat` - A plugin that uses the `sysinfo` crate to get
system statistics and sends them as `Measurement` messages. This is
a really involved plugin (code-size wise) and might require some
more effort to understand.
We did not yet introduce plugins for things like collectd, systemd, apt,
and so on in this work, as these are clearly _usecases_ and we want to
keep the plugin implementations we provide in this PR in the "this is an
example" space.
The work merged with this commit does not claim to provide the
end-result of anything! This is code, it can and most certainly will
be changed after this is merged to the `main` branch.
The most stable part of this PR is the `tedge_core` crate. The plugins
are only examples!
There are also some types defined for representing a `Measurement` for
example. This is not final by any means and its purpose is to be able
to implement example plugins! Of course we have to iterate on how a
Measurement (e.g.) should and can look like! The existing types for
representing a `Measurement` were not used in this PR because of
development-workflow reasons.
All changes that are merged with this commit are made under the DCO and
_not_ under any CLA.
DCO:
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
Signed-off-by: Marcel Müller <m.mueller@ifm.com>
Signed-off-by: Matthias Beyer <matthias.beyer@ifm.com>