Abscissa is a microframework for building Rust applications (either CLI tools or network/web services), aiming to provide a large number of features with a minimal number of dependencies, and with a strong focus on security.

Documentation

Features

• command-line option parsing: simple declarative option parser based on (i.e. forked from) [gumdrop]. The option parser in Abcissa contains numerous improvements which provide better UX and tighter integration with the other parts of the framework (e.g. overriding configuration settings using command-line options).
• components: Abscissa uses a component architecture (similar to an ECS) for extensibility/composability, with a minimalist implementation that still provides such features such as calculating dependency ordering and providing hooks into the application lifecycle. Newly generated apps use two components by default: terminal and logging.
• configuration: Simple parsing of TOML configurations to serde-parsed configuration types which can be dynamically updated at runtime.
• error handling: generic Error type based on the failure crate, and a unified error-handling subsystem.
• logging: based on the log to provide application-level logging.
• secrets management: the (optional) secrets module includes a Secret type which derives serde's Deserialize and can be used to represent secret values parsed from configuration files or elsewhere (e.g. credentials loaded from the environment or network requests)
• terminal interactions: support for colored terminal output (with color support autodetection). Useful for Cargo-like status messages with easy-to-use macros.

Requirements

• Rust 1.35+

Usage

If you already have Rust installed, the following commands will generate an Abscissa application skeleton:

This will generate a new Abscissa application in the my_cool_app directory. For more information, please see the Documentation.

Depencencies

or: "Know Your Dependencies"

One of Abscissa's primary goals is to maximize functionality while minimizing the number of dependencies. Abscissa is used in a number of high-security contexts, and as such we view each additional dependency as additional attack surface and therefore a potential liability. We have therefore been very conscientious about the dependencies we use and will not add additional dependencies without due consideration.

Here are all of Abscissa's transitive dependencies:

| # | Crate Name | Origin | License | unsafe? | Description | |----|------------------|-----------------|----------------|-----------|-------------------------| | 1 | [abscissa] | [iqlusion] | Apache-2.0 | yes | App microframework | | 2 | [backtrace] | [@alexcrichton] | Apache-2.0/MIT | yes | Capture stack traces | | 3 | [backtrace-sys] | [@alexcrichton] | Apache-2.0/MIT | yes | Capture stack traces | | 4 | [byteorder] | [@BurntSushi] | MIT/Unlicense | yes | Convert endianness | | 5 | [canonical-path] | [iqlusion] | Apache-2.0 | yes | Get canonical fs paths | | 6 | [chrono] | [chronotope] | Apache-2.0/MIT | yes | Time/date library | | 7 | [failure] | [@withoutboats] | Apache-2.0/MIT | no | Error handling | | 8 | [gumdrop] | [Murarth] | Apache-2.0/MIT | no | Command-line options | | 9 | [lazystatic] | [rust-lang] | Apache-2.0/MIT | yes | Heap-allocated statics | | 10 | [libc] | [rust-lang] | Apache-2.0/MIT | yes | C library wrapper | | 11 | [log] | [rust-lang] | Apache-2.0/MIT | yes | Logging facade library | | 12 | [num-integer] | [rust-num] | Apache-2.0/MIT | yes | Integer trait | | 13 | [num-traits] | [rust-num] | Apache-2.0/MIT | yes | Numeric traits | | 14 | [redoxsyscall] | [redox-os] | MIT | yes | Redox OS syscall API | | 15 | [rustc_demangle] | [@alexcrichton] | Apache-2.0/MIT | yes | Symbol demangling | | 16 | [semver] | [@steveklabnik] | Apache-2.0/MIT | yes | Semantic versioning | | 17 | [semver-parser] | [@steveklabnik] | Apache-2.0/MIT | no† | Parser for semver spec | | 18 | [serde] | [serde-rs] | Apache-2.0/MIT | yes | Serialization framework | | 19 | [termcolor] | [@BurntSushi] | MIT/Unlicense | no | Terminal color support | | 20 | [time] | [rust-lang] | Apache-2.0/MIT | yes | Time/date library | | 21 | [toml] | [@alexcrichton] | Apache-2.0/MIT | no | TOML parser library | | 22 | [winapi]§ | [@retep998] | Apache-2.0/MIT | yes | Windows API bindings | | 23 | [zeroize] | [iqlusion] | Apache-2.0/MIT | yes | Zero out sensitive data |

• † semver-parser has one usage of unsafe which is not compiled by Abscissa.
• § winapi also pulls in either [winapi-i686-pc-windows-gnu] or [winapi-x86_64-pc-windows-gnu] which are omitted for brevity.

Build / Development Dependencies

| # | Crate Name | Origin | License | unsafe? | Description | |----|-------------------|------------------|----------------|-----------|-------------------------| | 1 | [abscissaderive] | [iqlusion] | Apache-2.0 | no | Abscissa custom derive | | 2 | [cc] | [@alexcrichton] | Apache-2.0/MIT | yes | C/C++ compiler wrapper | | 3 | [cfg-if] | [@alexcrichton] | Apache-2.0/MIT | no | If-like #[cfg] macros | | 4 | [failurederive] | [@withoutboats] | Apache-2.0/MIT | no | failure custom derive | | 5 | [gumdropderive] | [Murarth] | Apache-2.0/MIT | no | Command-line options | | 5 | [proc-macro2] | [@alexcrichton] | Apache-2.0/MIT | yes | Shim for Macros 2.0 API | | 6 | [quote] | [@dtolnay] | Apache-2.0/MIT | no | Rust AST to token macro | | 7 | [serdederive] | [serde-rs] | Apache-2.0/MIT | no | serde custom derive | | 8 | [syn] | [@dtolnay] | Apache-2.0/MIT | yes | Rust source code parser | | 9 | [synstructure] | [@mystor] | Apache-2.0/MIT | no | syn structure macros | | 10 | [unicode-xid] | [unicode-rs] | Apache-2.0/MIT | no | Identify valid Unicode | | 11 | [version_check] | [@SergioBenitez] | Apache-2.0/MIT | no | rustc feature detection |

Dependency Relationships

The table below should help answer questions as to why a particular crate is an Abscissa dependency and whether or not it is optional. Abscissa uses [cargo features] to allow parts of it you aren't using to be easily disabled, so you only compile the parts you need.

| Crate Name | [Cargo Features] | Platform | Required By | |-------------------|------------------|-----------|-------------| | [abscissa] | mandatory | - | - | | [abscissaderive] | mandatory | - | [abscissa] | | [backtrace] | mandatory | - | [failure] | | [backtrace-sys] | mandatory | - | [backtrace] | | [canonical-path] | mandatory | - | [abscissa] | | [cc] | mandatory | - | [backtrace-sys], [zeroize] | | [cfg-if] | mandatory | - | [backtrace] | | [chrono] | time | - | [abscissa] | | [failure] | mandatory | - | [abscissa] | | [failurederive] | mandatory | - | [failure] | | [gumdrop] | options | - | [abscissa] | | [gumdropderive] | options | - | [gumdrop] | | [lazystatic] | mandatory | - | [abscissa] | | [log] | logging | - | [abscissa] | | [num-integer] | logging | - | [chrono] | | [num-traits] | logging | - | [chrono], [num-integer] | | [proc-macro2] | mandatory | - | [abscissaderive], [failurederive], [quote], [serdederive] | | [rustcdemangle] | mandatory | - | [backtrace] | | [semver] | application | - | [abscissa] | | [semver-parser] | application | - | [abscissa] | | [serde] | config | - | [abscissa] | | [serdederive] | config | - | [serde] | | [termcolor] | terminal | - | [abscissa] | | [time] | logging | - | [chrono] | | [unicode-xid] | mandatory | - | [proc-macro2] | | [versioncheck] | mandatory | - | [lazy_static] | | [zeroize] | mandatory | - | [abscissa] |

• § winapi also pulls in either [winapi-i686-pc-windows-gnu] or [winapi-x86_64-pc-windows-gnu] which are omitted for brevity.

Frequently Asked Questions (FAQ)

Q1: Why is it called "abscissa"?

A1: An abscissa represents the elevation of a point above the y-axis. In that regard, "Abscissa" can be thought of as a pun about getting off the ground, or elevating your project.

The word "abscissa" is also the key to the [Kryptos K2] panel.

Q2: "Abscissa" is a hard name to remember! Got any tips?

A2: Imagine you're A-B testing a couple of scissors... with attitude.

Testing Framework Changes

The main way to test framework changes is by generating an application with Abscissa's built-in application generator and running tests against the generated application (also rustfmt, clippy).

To generate a test application and test it automatically, you can simply do:

$ cargo test

However, when debugging test failures against a generated app, it's helpful to know how to drive the app generation and testing process manually. Below are instructions on how to do so.

If you've already run:

$ git clone https://github.com/iqlusioninc/abscissa/

...and are inside the abscissa directory and want to test your changes, you can generate an application by running the following command:

$ cargo run -- new /tmp/example_app --patch-crates-io='abscissa = { path = "$PWD" }'

This will generate a new Abscissa application in /tmp/example_app which references your local copy of Abscissa.

After that, change directory to the newly generated app and run the tests to ensure things are still working (the tests, along with rustfmt and clippy are run as part of the CI process):

$ cd /tmp/example_app # or 'pushd /tmp/example_app' and 'popd' to return $ cargo test $ cargo fmt -- --check # generated app is expected to pass rustfmt $ cargo clippy

Code of Conduct

We abide by the Contributor Covenant and ask that you do as well.

For more information, please see [CODEOFCONDUCT.md].

License

The abscissa crate is distributed under the terms of the Apache License (Version 2.0).

Copyright © 2018-2019 iqlusion

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.