BEACON
A system to continually watch interfaces for events and forward them respectively through the event bus
INSTALLATION
pip install pop-beacon
USAGE
beacon is mainly an app-merge component for larger projects. However, it includes a script that can be useful for testing your beacons. This testing script will listen to all beacons and print out events that any of them receive. A listener iterates over the internal beacon queues and prints everything that gets posted to them. The the outputter to format the printed data can be specified with –output.
beacon_test --output json
TESTING
Install beacon locally with testing libraries:
$ git clone git@gitlab.com:saltstack/pop/beacon.git
$ pip install -e beacon -r requirements-test.txt
If you have a rabbitmq-server binary installed via your system’s package manager, the pika tests won’t be skipped. Start a local rabbitmq-server with the default parameters:
sudo rabbitmq-server
Run the tests with pytest:
$ pytest beacon/tests
ACCT PROFILES
beacon will read credentials that are encrypted using the acct system. To use this system, create a yaml file that has the plaintext credentials and information needed to connect with the various beacon plugins. For example, to connect to a rabbitmq server, or any amqp implementation, have a profile in your acct credentials file that specifies the “pika” acct plugin:
credentials.yml
pika:
profile_name:
host: localhost
port: 5672
username: XXXXXXXXXXXX
password: XXXXXXXXXXXX
beacon_channels:
- channel1
- channel2
Next use the acct command to encrypt this file using the fernet algorithm:
$ acct encrypt credentials.yml
YeckEnWEGOjBDVxxytw13AsdLgquzhCtFHOs7kDsna8=
The acct information can now be stored in environment variables:
$ export ACCT_FILE = $PWD/credentials.yml.fernet
$ export ACCT_KEY = "YeckEnWEGOjBDVxxytw13AsdLgquzhCtFHOs7kDsna8="
They can also be used on the command line:
$ beacon_test --acct-file=credentials.yml.fernet --acct-key="YeckEnWEGOjBDVxxytw13AsdLgquzhCtFHOs7kDsna8="
INTEGRATION
Your own app can extend acct’s command line interface to use the –acct-file and –acct-key options for beacon:
my_project/conf.py
CLI_CONFIG = {
"acct_file": {"source": "acct", "os": "ACCT_FILE"},
"acct_key": {"source": "acct", "os": "ACCT_KEY"},
"beacon_profiles": {"source": "beacon"},
}
In your own project, you can vertically merge beacon and extend it with your own beacon plugins:
my_project/conf.py
DYNE = {
"acct": ["acct"],
"beacon": ["beacon"],
"my_project": ["my_project"],
}
Create the directory my_project/beacon and add your beacon plugins there.
Beacon plugins need a function called “listen” that is an asynchronous generator.
my_project/beacon/my_plugin.py
from typing import AsyncGenerator
async def listen(hub) -> AsyncGenerator:
async for event in my_queue:
yield event
The “listen” function can optionally have a ctx parameter if your beacon plugin requires login credentials. The ctx parameter will be automatically be populated by acct and evbus if a profile that specifies your plugin is included in the encrypted acct file.
my_project/beacon/my_plugin.py
from typing import AsyncGenerator
async def listen(hub, ctx) -> AsyncGenerator:
if not ctx.connected:
return
# Many message queues have named channels that can be specified
# Create a listener for every channel on this connection
# A listener is another function that returns an async generator
channel_listeners = [
await ctx.connection.channel_listener(channel) for channel in ctx.channels
]
# Use hub.pop.loop.as_yielded to combine all the channel async generators into a single async generator
generator = hub.pop.loop.as_yielded(channel_listeners)
# Listen for events as they come from any of the channels
async for event in generator:
yield event
Create the directory my_project/acct/beacon and add your acct plugins there. acct plugins need to implement a gather function, which reads the appropriate information from hub.acct.PROFILES and turns it into processed profile information in hub.acct.SUB_PROFILES. This processing can include operations such as opening a connection to a remote server.
my_project/acct/beacon/my_plugin.py
async def gather(hub):
"""
Get [my_plugin] profiles from an encrypted file
Example:
.. code-block:: yaml
my_plugin:
profile_name:
host: localhost
port: 12345
username: XXXXXXXXXXXX
password: XXXXXXXXXXXX
beacon_channels:
- channel1
- channel2
"""
sub_profiles = {}
for profile, ctx in hub.acct.PROFILES.get("my_plugin", {}).items():
# Create a connection through [some_library] for each of the profiles
sub_profiles[profile] = {
"connected": False,
"connection": await some_library.connect(**ctx),
"channels": ctx.pop("beacon_channels", []),
}
# Return these to be automatically processed by acct and injected into the `ctx` parameter of appropriate beacon publish calls.
return sub_profiles
Add beacon startup code to your project’s initializer:
my_project/my_project/init.py
def __init__(hub):
# Horizontally merge the beacon dynamic namespace into your project
hub.pop.sub.add(dyne_name="beacon")
def cli(hub):
# Load the config from beacon onto hub.OPT
hub.pop.config.load(["my_project", "beacon", "evbus", "acct"], cli="my_project")
# Create the asyncio loop
hub.pop.loop.create()
# Create the beacon coroutine
coro = hub.beacon.init.start(
format_plugin=hub.OPT.beacon.format,
acct_file=hub.OPT.acct.acct_file,
acct_key=hub.OPT.acct.acct_key,
beacon_profiles=hub.OPT.beacon.beacon_profiles,
)
# Start the main beacon listener
hub.pop.Loop.run_until_complete(coro)
Metadata
Release files for pop-beacon 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pop-beacon-3.0.0.tar.gz | 14.2 kB | Without provenance | Details for pop-beacon-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pop_beacon-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for pop_beacon-3.0.0-py3-none-any.whl |
Total release size: 29.6 kB
Release files / pop-beacon-3.0.0.tar.gz
| Download URL | pop-beacon-3.0.0.tar.gz |
|---|---|
| Size | 14.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
30e3fecb5393daea0895594d2335f1eec4cb6b114982282f5accaf09ca5389e5
|
|
BLAKE2b-256 checksum How to use checksums |
b71527662bbc9b6fb567e67d7e278afb791565c281bbe1579ab77051683b5d19
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.7
|
Release files / pop_beacon-3.0.0-py3-none-any.whl
| Download URL | pop_beacon-3.0.0-py3-none-any.whl |
|---|---|
| Size | 15.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1736b5a47bdfc10fe93de09b08036b105ee71789c67d1a6c97cd96e1c3ca4061
|
|
BLAKE2b-256 checksum How to use checksums |
e39b3ffcf5585b78ffe181857338232293ac19d82bced47047cda25f61d2d5f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.7
|
Security for pop-beacon 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.