#abscissa #cli #application #framework #service

abscissa_core

Application microframework with support for command-line option parsing, configuration, error handling, logging, and terminal interactions. This crate contains the framework’s core functionality

9 unstable releases (3 breaking)

✓ Uses Rust 2018 edition

0.5.2 Jan 30, 2020
0.5.1 Jan 12, 2020
0.5.0 Dec 17, 2019
0.4.0 Oct 13, 2019
0.2.1 Jul 27, 2019

#28 in Configuration

Download history 2932/week @ 2019-12-17 1869/week @ 2019-12-24 2545/week @ 2019-12-31 3442/week @ 2020-01-07 3323/week @ 2020-01-14 4415/week @ 2020-01-21 6096/week @ 2020-01-28 5614/week @ 2020-02-04 3812/week @ 2020-02-11 3508/week @ 2020-02-18 3857/week @ 2020-02-25 4536/week @ 2020-03-03 4450/week @ 2020-03-10 4347/week @ 2020-03-17 4783/week @ 2020-03-24 4350/week @ 2020-03-31

13,209 downloads per month
Used in 26 crates (11 directly)

Apache-2.0 and maybe MPL-2.0

120KB
2.5K SLoC

Abscissa

Crate Docs Apache 2.0 Licensed MSRV Safety Dance Build Status Gitter Chat

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 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: unified error-handling subsystem with generic error type.
  • 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.

Projects Using Abscissa

  • Canister: deployment utility for "distroless" containers/microVMs
  • cargo-audit: audit Cargo projects for security vulnerabilities
  • cargo-rpm: build RPMs out of Cargo projects
  • OpenLibra: open platform for financial inclusion. Not run by Facebook.
  • Sagan: observability tool for Tendermint applications
  • Synchronicity: distributed build system providing BFT proofs-of-reproducibility
  • Tendermint KMS: key management system for Tendermint applications
  • Zebra: Rust implementation of a Zcash node

Crate Structure

Abscissa presently consists of three crates:

  • abscissa: CLI app and application generator - cargo install abscissa
  • abscissa_core: main framework library
  • abscissa_derive: custom derive support - implementation detail of abscissa_core

Requirements

  • Rust 1.36+

Installation

To generate a new Abscissa application, install the abscissa CLI utility:

$ cargo install abscissa

Usage

After installing the abscissa CLI utility using the method above, run abscissa new <my_app> to generate a new application:

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 when configured with the default set of features in the application:

# Crate Name Origin License Description
1 abscissa_core iqlusion Apache-2.0 Abscissa framework
2 aho-corasick @BurntSushi MIT/Unlicense Pattern-matching alg
3 ansi_term @ogham MIT Terminal color libray
4 arc-swap @vorner Apache-2.0/MIT Atomic swap for Arc
5 atty @softprops MIT Detect TTY presence
6 autocfg @cuviper Apache-2.0/MIT Rust compiler configs
7 backtrace @alexcrichton Apache-2.0/MIT Capture stack traces
8 backtrace-sys @alexcrichton Apache-2.0/MIT Capture stack traces
9 byteorder @BurntSushi MIT/Unlicense Byte order conversions
10 canonical-path iqlusion Apache-2.0 Get canonical fs paths
11 chrono chronotope Apache-2.0/MIT Time/date library
12 color-backtrace @athre0z Apache-2.0/MIT Rich colored backtraces
13 generational-arena @fitzgen MPL-2.0 Component allocator
14 gumdrop @Murarth Apache-2.0/MIT Command-line options
15 lazy_static rust-lang Apache-2.0/MIT Heap-allocated statics
16 libc rust-lang Apache-2.0/MIT C library wrapper
17 log rust-lang Apache-2.0/MIT Logging facade library
18 matchers @hawkw MIT Stream regex matching
19 maybe-uninit @est31 Apache-2.0/MIT MaybeUninit compat
20 memchr @BurntSushi MIT/Unlicense Optimized byte search
21 num-integer rust-num Apache-2.0/MIT Integer trait
22 num-traits rust-num Apache-2.0/MIT Numeric traits
23 once_cell @matklad Apache-2.0/MIT Single assignment cells
24 owning_ref @Kimundi MIT Owner-carrying refs
25 redox_syscall redox-os MIT Redox OS syscall API
26 regex rust-lang Apache-2.0/MIT Regular expressions
27 regex-automata @BurntSushi MIT/Unlicense Low-level regex DFAs
28 regex-syntax rust-lang Apache-2.0/MIT Regex syntax impl
29 rustc-demangle @alexcrichton Apache-2.0/MIT Symbol demangling
30 secrecy iqlusion Apache-2.0 Secret-keeping types
31 semver @steveklabnik Apache-2.0/MIT Semantic versioning
32 semver-parser @steveklabnik Apache-2.0/MIT Parser for semver spec
33 serde serde-rs Apache-2.0/MIT Serialization framework
34 signal-hook @vorner Apache-2.0/MIT Unix signal handling
35 signal-hook-registry @vorner Apache-2.0/MIT Unix signal registry
36 smallvec servo Apache-2.0/MIT Optimized small vectors
37 spin @mvdnes MIT Spinlock for no_std
38 stable_deref_trait @Storyyeller Apache-2.0/MIT Stable addr marker
39 termcolor @BurntSushi MIT/Unlicense Terminal color support
40 thread_local @Amanieu Apache-2.0/MIT Per-object thread local
41 time rust-lang Apache-2.0/MIT Time/date library
42 toml @alexcrichton Apache-2.0/MIT TOML parser library
43 tracing tokio-rs MIT App tracing / logging
44 tracing-core tokio-rs MIT App tracing / logging
45 tracing-log tokio-rs MIT log compatibility
46 tracing-subscriber tokio-rs MIT Tracing subscribers
47 utf8-ranges @BurntSushi MIT/Unlicense UTF-8 codepoint ranges
48 winapi§ @retep998 Apache-2.0/MIT Windows FFI bindings
49 winapi-util @BurntSushi MIT/Unlicense Safe winapi wrappers
50 wincolor @BurntSushi MIT/Unlicense Windows console color
51 zeroize iqlusion Apache-2.0/MIT Zero out sensitive data

Build / Development / Testing Dependencies

# Crate Name Origin License Description
1 abscissa_derive iqlusion Apache-2.0 Abscissa custom derive
2 cc @alexcrichton Apache-2.0/MIT C/C++ compiler wrapper
3 cfg-if @alexcrichton Apache-2.0/MIT If-like #[cfg] macros
4 darling @TedDriggs MIT Nifty attribute parser
5 darling_core @TedDriggs MIT Attribute parser core
6 darling_macro @TedDriggs MIT Attribute parser macros
7 fnv @alexcrichton Apache-2.0/MIT Fast hash function
8 gumdrop_derive @Murarth Apache-2.0/MIT Command-line options
9 ident_case @TedDriggs Apache-2.0/MIT Case conversion utils
10 proc-macro2 @alexcrichton Apache-2.0/MIT Shim for Macros 2.0 API
11 quote @dtolnay Apache-2.0/MIT Rust AST to token macro
12 serde_derive serde-rs Apache-2.0/MIT serde custom derive
13 strsim @dguo MIT String similarity utils
14 syn @dtolnay Apache-2.0/MIT Rust source code parser
15 synstructure @mystor Apache-2.0/MIT syn structure macros
16 thiserror @dtolnay Apache-2.0/MIT Error custom derive
17 tracing-attributes tokio-rs MIT App tracing / logging
18 unicode-xid unicode-rs Apache-2.0/MIT Identify valid Unicode
19 wait-timeout @alexcrichton Apache-2.0/MIT Timeouts for waitpid

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 Required By
abscissa_core -
abscissa_derive - abscissa_core
aho-corasick trace, testing regex
ansi_term trace tracing-subscriber
arc-swap signals signal-hook-registry
atty terminal color-backtrace
autocfg time num-integer
backtrace - abscissa_core
backtrace-sys - backtrace
byteorder trace regex-automata
canonical-path - abscissa_core
cc - backtrace-sys
cfg-if - backtrace, log
color-backtrace terminal abscissa_core
chrono time abscissa_core
darling - abscissa_derive
darling_core - darling, darling_macro
darling_macro - darling
fnv - darling_core
generational-arena application abscissa_core
gumdrop options abscissa_core
gumdrop_derive options gumdrop
ident_case - abscissa_derive, darling_core
lazy_static testing, trace thread_local, tracing-core, tracing-log, tracing-subscriber
libc signals abscissa_core
log logging abscissa_core
matchers trace tracing-subscriber
memchr trace, testing aho-corasick
maybe-uninit trace smallvec
num-integer time chrono
num-traits time chrono, num-integer
once_cell - abscissa_core
owning_ref trace tracing-subscriber
proc-macro2 - abscissa_derive, darling, quote, serde_derive, syn
quote - abscissa_derive, darling, gumdrop_derive, serde_derive
redox_syscall time time
regex trace, testing abscissa_core
regex-automata trace matchers
regex-syntax trace, testing abscissa_core
rustc-demangle - backtrace
secrecy secrets abscissa_core
semver application abscissa_core
semver-parser application abscissa_core
serde config abscissa_core
serde_derive config serde
signal-hook signals abscissa_core
signal-hook-registry signals signal-hook
smallvec trace tracing-subscriber
strsim - darling_core
spin testing, trace lazy_static, tracing, tracing-core
stable_deref_trait trace owning_ref
syn - abscissa_derive, darling, gumdrop_derive, serde_derive
termcolor terminal abscissa_core
thiserror - Abscissa boilerplate
thread_local trace, testing regex
time logging chrono
tracing trace abscissa_core
tracing-attributes trace tracing
tracing-core trace tracing
tracing-log trace abscissa_core
tracing-subscriber trace abscissa_core
unicode-xid - proc-macro2, syn
utf8-ranges trace, testing regex
wait-timeout testing abscissa_core
winapi§ - termcolor, time, winapi-util
winapi-util - termcolor
wincolor terminal termcolor
zeroize - abscissa_core

Frequently Asked Questions (FAQ)

Q1: Why is it called "abscissa"?

A1: The word "abscissa" is 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 CODE_OF_CONDUCT.md.

License

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

Copyright © 2018-2020 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

If you are interested in contributing to this repository, please make sure to read the CONTRIBUTING.md and CODE_OF_CONDUCT.md files first.

Dependencies

~1–2.7MB
~55K SLoC