Idiomatic Rust Roadmap

[vkkoskie]

@ionut-arm mentioned wanting a roadmap to be able to plan around features and changes I may be submitting. I don't think I can do that in any comprehensive way because I'm a bit more opportunistic than that, just changing the thing that was in my way most recently. But I can at least try to collect ideas here that have crossed my mind.

In general I've been working from the bottom up, trying to work out the details of the low-level types first and moving gradually in the direction of the main library API.

Next-ish:

• Use thiserror to clean up the Error type.
• Expand Error strings to be more context-specific. (i.e, Two errors with the same source type aren't necessarily the same).
• This one's dumb, but remove use of derivative crate. Its only used in one place where a custom Debug impl will do. My real motive, though, is that it does some things that make rust-analyzer incorrectly mark it with a red squiggly, which is annoying. 😛
• Take another look at Attributes and Objects.
  • Use OASIS headers to confirm enumerated types are complete.
  • Unexpose type bindings from the FFI crate.
  • Possibly privatize/remove AttributeType in favor of just Attribute.
  • Make a first attempt at a correct implementation of CKA_VENDOR_DEFINED and set a general pattern for other vendor definitions.
  • Think about providing predefined Attribute templates for objects. Or, have callbacks that build a private template, query for it, and respond with a Rust type representing the object (so clients don't use attributes at all in the most common cases).
  • Update the Date type to resemble the UtcTime type in Info flags refactor #68. Likely also move it out of types and into object since it isn't used elsewhere.
• Consider an organization for mechanism submodules that will make navigating such a huge number of items as easy as possible both for users and contributors.

"As I go" items I'll change as I encounter them but are too spread out for their own PR:

• Flatten all structs containing only a single CK struct, into a Rust equivalent of the inner struct.
• For the above, implement From or TryFrom conversion at the struct level rather than converting inside getters.
• Change all one-element structs that wrap a primitive type to named tuples. E.g., MyStruct{ var: CK_ULONG } should just be MyStruct(CK_ULONG).
• Replace informal tone in many doc comments. Pull information and/or phrasing from the standard wherever possible.
• Prevent exposure of any bare types from the FFI in the abstraction crate. This includes hiding public trait impls like From from docs and replacing the large stringify blocks with Debug impls of Rust types.
• Generally try to keep items out of the types module. For instance, I put the MaybeUnavailable trait there because I thought it might need use in multiple places. But if that doesn't materialize, it should be moved back near TokenInfo, the only place it's used now.

Bigger, speculative ideas that may become more or less unrealistic as other changes progress:

• Use a builder pattern to set options for the few constructor-like callbacks. (e.g., initializing the library, opening a session).
• Possibly merge Thing and ThingInfo type pairs. It's strange that many types have a secondary info type. To just have something that can act as both a handle/ID as well as describe itself seems much more intuitive. (Slot looks especially absurd in this regard.) I haven't thought through all the implications of such a change, though. For one, it would make all get_info kinds of calls implicit whenever the thing being described is constructed. Also, any dynamic state (e.g., clock value) would have to be managed in a new way. Lots of other stuff I'm probably not thinking of, too.
• Use Arc of lib to spread context callback access into other types. Use lifetime of the Session that provides them to prevent use after close.
• As they grow, gate groups of related mechanisms with crate features to prevent such a huge list being imported by default by clients.
• When available, separate v2.40 and v3.0 details with feature gates, so a single crate can provide both. Whether or not these are mutually exclusive (allowing client code to check at runtime which to use) may be difficult.
• Look at cost/benefit of replacing use cryptoki_sys::* globs with an explicit list of bindings. This is more curiosity than anything. I'd like to dig into how the import process works and whether there's anything to be gained by not having this massive file fully in scope.

[vkkoskie]

Adding to the as-I-go list:

• Make most/all conversions from bindings of C structs into Rust types fallible (From -> TryFrom). The bindings do not provide any degree of validity checks, so the conversions should be fairly aggressive on that front.

[ionut-arm]

1. This is a great list, but I'm thinking of moving it into an issue and pinning it. I think most people look at the Issues tab and if someone would be interested in contributing, this list should be the place to start.

2. Another item for the list: more tests.... we have very few of them, definitely need a lot more (or maybe I've grown out of touch with the repo? the issue in Segmentation fault on parsing Date #74 would've been easy to catch with some integration tests)