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

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.

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, 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.

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).

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

Write the initial README.md:

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

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().

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.

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

• Move options unit tests
• Move lines unit tests

Background

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

Requirements

• Add a command line option to set the TTL.

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.

AliasesFile is central to the correct operation of both avahi-alias and avahi-alias-daemon. However, it lacks 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.

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

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.

Testing line coverage on the library is spotty.

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.

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

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

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

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.

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

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

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 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

References

• IETF RFC 5891
• Internationalized domain name on Wikipedia

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.

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, binaries must use AliasesFile via its module (i.e., use aliases::AliasesFile). Since the library is simple, exposing AliasesFile directly.

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.

Background

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

Requirements

• Add a command line option to set the timeout.

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.

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.

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.

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.