scott-ainsworth / avahi-aliases-rs Goto Github PK

Currently, avahi-alias-deamon polls for changes to /etc/avahi/avahi-aliases, which is primitive and inefficient. Two possibilities for change detection are subscribing to file system events, signalling, and service restart.

Discussion

Event subscription: File system event subscription is efficient. However, it varies by operating system and can fail (e.g., due to capacity limits). Thus, a fall back is needed. The fall back could be polling or signaling.

Signalling: Sending a daemon a HUP signal is a long-standing method to have a daemon reload data. However, it only notifies under limited circumstances. In this case, when avahi-alias makes changes. Editing the aliases files directly will not send a signal to the daemon. Thus, a fall back is needed. This is likely to be service restart.

Service Restart: This is built in to both systemd and init.d.

Requirements

• Choose a change detection method.
• Implement change detection

Moving unit tests into submodules eliminates false "not used" messages.

• Move options unit tests
• Move lines unit tests

The visibility and naming of modules, structs, functions, etc. in the avahi-aliases library evolved somewhat randomly over time.

• Clean up public symbols.
• Rename public symbols as needed for good semantic naming.

• Implement resource record module
• Implement CNAME encoding
• Implement resource record encoding
• Implement and test syslog logging
• Add syslog command line options

Currently, the library is a mix of specialized support for the binaries (avahi-alias and avahi-alias-daemon) and a rudimentary Avahi D-Bus client. Separating the Avahi D-Bus client code will simplify using a third-party library of generated code. Additionally, the generated D-Bus code should be a submodule of the Avahi D-Bus client.

Requirements

• Refactor the Avahi client code into an independent package.

Testing line coverage on the library is spotty.

For the daemon, the option to send log entries to syslog (vice the console) is needed.

• Add init_syslog()

The syslog module can generate multiple error types.

• Add LoggingError enum to manage the error types.

LoggingError is the original error wrapper and is now OBE. Merge it into ErrorWrapper.

• Move SyslogError and SetLoggerError into ErrorWrapper.
• Add new_... functions.
• Add unit tests.
• Delete LoggingError.
• Fixup avahi-alias.
• Fixup avahi-alias-daemon (if needed).

Currently, a Makefile file is to strip release binaries. However, Cargo now has this built in (requires +nightly).

Requirements

• Switch from using Make to Cargo's built-in capability.

Currently avahi-alias-daemon checks for alias file changes every 5 seconds.

Requirements

• Add a --poll-interval command line option.
• Change the default to 30 seconds.

Notes

• Ultimately, instead of polling, (1) the daemon could subscribe to file system events or (2) avahi-alias could signal a change (HUP?) #37

avahi-alias does not set exit status. Set exit status to 0 on success and 1 on error.

The avahi-alias command displays error message (e.g., "No such file or directory") in debug form. They should be displayed in a more human-friendly form.

The messaging lacks unit tests.

• Implement unit tests for the compute_log_level() function.
• Correct resulting bugs.

Functionality

• Encode IDNA names #24
• Follow Avahi publishing guidelines #30
• Add --ttl option to the daemon #46
• Add --timeout options to the daemon #47
• General housekeeping #51
• Add integration test for avahi-alias #53
• Validate --poling-interval, --timeout, and --ttl` #56
• Upgrade third-party packages #58
• Cleanup lints #59

Process and Delivery

• Implement GitHub actions to verify pull requests #26
• Implement GitHub actions to create releases

avahi-alias Command Line Utility Requirements

• Add, remove, and list aliases (avahi-alias command).
• Ignore comments and extraneous whitespace in aliases files.
• Overhaul error:ErrorWrapper to minimize borrows. #15
• Validate aliases. #14

avahi-alias-daemon Requirements

• Overview: #6
• Operate at the command line.
• Operate under systemd.
• Log to syslog if requested. #12
• Poll for alias file changes (vice hooking to file system change events).
• Specify polling interval (--poll-time option, default: 5 sec.). #36

Common requirements

• Write README.md. #1
• Specify the alias file to use (--file option, default: /etc/avahi/avahi-aliases)
• Specify the level of verbosity (--verbose option or --quiet option, default: false)
• Specify debug-level logging (--debug option, default: false)

Currently, an alias comprises all provided characters less leading and trailing whitespace. This can yield invalid aliases (e.g., my alias.local)

Requirements

• Validate all aliases, both in the aliases file and specified on the command line, meet naming requirements.
• avahi-alias list must flag invalid aliases in the alias listing.
• avahi-alias add must make no changes when invalid aliases are found on the command line or in the aliases file.
• avahi-alias remove must make no changes when invalid aliases are found on the command line.
• avahi-alias remove must make no changes when invalid aliases are found in the aliases files unless the --remove-invalid option is specified.
• avahi-alias remove --force must remove all invalid aliases from the aliases file.
• avahi-alias-daemon must log and ignore invalid aliases found in the aliases file.

Notes

• It is not clear if non-.local CNAMES are allowed by the specification or in practical application. Since RFC 6762 indicates that using Multicast DNS for non-.local domains is a fail-over option that should be disabled by default, version 1 will only allow .local CNAMES.

References

• IETF RFC 6762

When the avahi-aliases file is empty, avahi-aliases-daemon attempts to commit the Avahi entry group anyway. The commit returns an is-empty status, which is interpreted as a failure. Instead, a warning should be logged and the daemon should continue to execute.

Background

Some other implementations of avahi-aliases support loading additional aliases from files in /etc/avahi/avahi-aliases.d. Although avahi-alias supports editing these files (using the --file option), avahi-alias-daemon does not use them.

Requirements

• Modify avahi-alias-daemon to load aliases from files in /etc/avahi/avahi-aliases.d.
• Allow a command-line option to change the directory.
• Allow a command-line option to disable loading aliases from the directory.

Logging for avahi-aliases and avahi-aliases-daemon differs only in the destination of the log entries. This difference can be handled through two separate initializations.

• Rename messaging to logging
• Move logging into the library
• Rename init() to init_console().

Background

The D-Bus connection timeout is is currently fixed at 60 seconds.

Requirements

• Add a command line option to set the timeout.

Currently there are no integration tests for the alias managers (avahi-alias) or daemon (avahi-alias-daemon).

Requirements

• Test the add command.
• Test the remove command.
• Test the list command.
• Ensure all three work if comments exist.

Determine which license(s) to allow. MIT and Apache are popular. Avahi itself is GNU Lesser.

Requirements

• Update the license files.
• Add licensing header to source files.

Background

The time-to-live (TTL) for CNAMEs is currently fixed at 60 seconds.

Requirements

• Add a command line option to set the TTL.

Write the initial README.md:

• Project description
• Version 1 goals
• Contribution
• References
• Credits

The aliases module has only two structs yet the module is in a subdirectory. Consider moving the structs directly under src/.

Upgrade the

• sysinfo package to 0.22.2 and
• syslog package to 6.0.0.

Note: syslog changes the type of syslog::Formatter3164::pid from i32 to u32, while sysinfo::get_current_pid() still return i32.

Currently, binaries must use AliasesFile via its module (i.e., use aliases::AliasesFile). Since the library is simple, exposing AliasesFile directly.

Problem

Currently the --polling-interval, --timeout, and --ttl options accept any u64 value.

Requirements

• Add range validation for --polling-interval: 10 – 60 seconds.
• Add range validation for --timeout: 10 – 300 seconds.
• Add range validation for --ttl: 0 – 2³¹-1 seconds.

Currently, lints are handled using the nightly version of Rust and enables lints only available in the nightly version. Additionally, many normally-allowed lints are enabled by adding #![warn(...)] lines to the source (which is ugly).

Requirements

• Enable lints in .cargo/config.toml.
• Cleanup code to eliminate lints.

The binaries (avahi-alias and avahi-alias-daemon) seem much larger than their functionality should require. There is much discussion of this, but no solutions for distribution that achieve anything comparable to C with shared libraries.

References

• min-sized-rust documentation on Github.
• Making executables smaller discussion on Rust users forum.

Currently, error::ErrorWrapper borrows most string values. Since ErrorWrapper needs to be passed up the stack for handling in user-aware code, this leads to nearly-impossible-to-resolve lifetime issues.

• Modify all ErrorWrapper enum variants to make copies of references.

Technically, an alias is a CNAME. However, in Avahi CNAMEs have been called aliases for long enough for the term to stick. Thus, instead of using alias vice CNAME reduces the learning/communication curve.

The way CNAMEs are currently published is a hack inherited from the origin Python example. Modify the code to follow the rules.

References

• https://www.avahi.org/doxygen/html/#good_publish

The command-line options code originated in avahi-alias. Parts are now duplicated in avahi-alias-daemon. Achieve DRY principles by refactoring the code into the library:

• Move the avahi-alias options module into the library.
• Delete the avahi-alias-daemon options.
• Rename options.Args to options.CommandOpts.
• Expose CommonOpts, Command, and CommandOpts.
• Update avahi-alias to use CommandOpts.
• Update avahi-alias-daemon to use CommonOpts.
• Create unit tests.

Requirements

• Exclude .rustfmt from spell check.
• Synchronize Makefile and tasks.json build options to minimize rebuilds.
• Makefile inconsistencies cleanup.
• Add issue number to in-code to-do comments.

AliasesFile is central to the correct operation of both avahi-alias and avahi-alias-daemon. However, it lacks unit tests.

References

• IETF RFC 5891
• Internationalized domain name on Wikipedia