Update README with cargo-rdme

Author: Bennett Hardwick

README.md

@@ -51,10 +51,21 @@ Upload it to ZeroKMS using the following command:
 
 ---
 
-### Setup DynamoDB
+<!-- cargo-rdme start -->
+
+###### Cryptonamo: Encrypted Tables for DynamoDB
+
+Based on the CipherStash SDK and ZeroKMS key service, Cryptonamo provides a simple interface for
+storing and retrieving encrypted data in DynamoDB.
+
+###### Usage
 
 To use Cryptonamo, you must first create a table in DynamoDB.
-The table must have a primary key and sort key, both of type String.
+The table must have a at least partition key, sort key, and term field - all of type String.
+
+Cryptonamo also expects a Global Secondary Index called "TermIndex" to exist if you want to
+search and query against records. This index should project all fields and have a key schema
+that is a hash on the term attribute.
 
 You can use the the `aws` CLI to create a table with an appropriate schema as follows:
 
@@ -69,44 +80,45 @@ aws dynamodb create-table \
         AttributeName=pk,KeyType=HASH \
         AttributeName=sk,KeyType=RANGE \
     --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5 \
-    --global-secondary-indexes "IndexName=TermIndex,KeySchema=[{AttributeName=term,KeyType=HASH},{AttributeName=pk,KeyType=RANGE}],Projection={ProjectionType=ALL},ProvisionedThroughput={ReadCapacityUnits=5,WriteCapacityUnits=5}"
+    --global-secondary-indexes "IndexName=TermIndex,KeySchema=[{AttributeName=term,KeyType=HASH}],Projection={ProjectionType=ALL},ProvisionedThroughput={ReadCapacityUnits=5,WriteCapacityUnits=5}"
 ```
 
 See below for more information on schema design for Cryptonamo tables.
 
-#### Annotating a Cryptanomo Type
+####### Annotating a Cryptanomo Type
 
-To use Cryptonamo, you must first annotate a struct with the the derive macros for the Cryptonamo traits you wish to implement.
+To use Cryptonamo, you must first annotate a struct with the `Encryptable` derive macro, as
+well as the `Searchable` and `Decryptable` macros if you want to support those features.
 
 ```rust
-use cryptonamo::{Encryptable, Decryptable, Searchable};
+use cryptonamo::{Searchable, Decryptable, Encryptable};
 
-#[derive(Debug, Encryptable, Decryptable, Searchable)]
+#[derive(Debug, Searchable, Decryptable, Encryptable)]
 struct User {
     name: String,
-
     #[partition_key]
     email: String,
 }
 ```
 
-This example implements the traits:
+These derive macros will generate implementations for the following traits of the same name:
 
-* `Decryptable` - a trait that allows you to decrypt the record from DynamoDB
-* `Encryptable` - a trait that allows you to encrypt the record for storage in DynamoDB
+* `Decryptable` - a trait that allows you to decrypt a record from DynamoDB
+* `Encryptable` - a trait that allows you to encrypt a record for storage in DynamoDB
 * `Searchable`  - a trait that allows you to search for records in DynamoDB
 
 The above example is the minimum required to use Cryptonamo however you can expand capabilities via several macros.
 
-#### Controlling Encryption
+####### Controlling Encryption
 
-By default, all fields on a `Cryptanomo` type are encrypted and stored in the index.
-To store a field as a plaintext, use the `plaintext` attribute:
+By default, all fields on an annotated struct are stored encrypted in the table.
+
+To store a field as a plaintext, you can use the `plaintext` attribute:
 
 ```rust
-use cryptonamo::Cryptonamo;
+use cryptonamo::{Searchable, Decryptable, Encryptable};
 
-#[derive(Cryptonamo)]
+#[derive(Debug, Searchable, Decryptable, Encryptable)]
 struct User {
     #[partition_key]
     email: String,
@@ -117,22 +129,34 @@ struct User {
 }
 ```
 
-Most basic rust types will work automatically but you can implement a conversion trait for [Plaintext] to support custom types.
+If you don't want a field stored in the the database at all, you can annotate the field with `#[cryptonamo(skip)]`.
 
 ```rust
-impl From<MyType> for Plaintext {
-    fn from(t: MyType) -> Self {
-        t.as_bytes().into()
-    }
+use cryptonamo::{Searchable, Encryptable, Decryptable};
+
+#[derive(Debug, Searchable, Encryptable, Decryptable)]
+struct User {
+    #[partition_key]
+    email: String,
+    name: String,
+
+    #[cryptonamo(skip)]
+    not_required: String,
 }
 ```
 
-If you don't want a field stored in the the database at all, you can annotate the field with `#[cryptonamo(skip)]`.
+If you implement the `Decryptable` trait these skipped fields need to implement `Default`.
+
+####### Sort keys
+
+Cryptanomo requires every record to have a sort key. By default this will be derived based on the name of the struct.
+However, if you want to specify your own, you can use the `sort_key_prefix` attribute:
 
 ```rust
-use cryptonamo::Cryptonamo;
+use cryptonamo::Encryptable;
 
-#[derive(Cryptonamo)]
+#[derive(Debug, Encryptable)]
+#[cryptonamo(sort_key_prefix = "user")]
 struct User {
     #[partition_key]
     email: String,
@@ -143,68 +167,93 @@ struct User {
 }
 ```
 
-#### Sort keys
+######## Dynamic Sort keys
 
-Cryptanomo requires every record to have a sort key and it derives it automatically based on the name of the struct.
-However, if you want to specify your own, you can use the `sort_key_prefix` attribute:
+Cryptonamo also supports specifying the sort key dynamically based on a field on the struct.
+You can choose the field using the `#[sort_key]` attribute.
 
 ```rust
-use cryptonamo::Cryptonamo;
+use cryptonamo::Encryptable;
 
-#[derive(Cryptonamo)]
-#[cryptonamo(partition_key = "email")]
-#[cryptonamo(sort_key_prefix = "user")]
+#[derive(Debug, Encryptable)]
 struct User {
+    #[partition_key]
+    email: String,
+    #[sort_key]
     name: String,
 
     #[cryptonamo(skip)]
     not_required: String,
 }
 ```
-Note that you can `skip` the partition key as well.
-In this case, the data won't be stored as an attribute table but a hash of the value will be used for the `pk` value.
 
-### Indexing
+Sort keys will contain that value and will be prefixed by the sort key prefix.
+
+###### Indexing
 
 Cryptanomo supports indexing of encrypted fields for searching.
-Exact, prefix and compound match types are all supported.
+Exact, prefix and compound match types are currently supported.
 To index a field, use the `query` attribute:
 
 ```rust
-use cryptonamo::Cryptonamo;
+use cryptonamo::Encryptable;
 
-#[derive(Cryptonamo)]
+#[derive(Debug, Encryptable)]
 struct User {
     #[cryptonamo(query = "exact")]
     #[partition_key]
     email: String,
-
+    
    #[cryptonamo(query = "prefix")]
     name: String,
 }
 ```
 
 You can also specify a compound index by using the `compound` attribute.
-All indexes with the same compound name are combined into a single index.
+Indexes with the same name will be combined into the one index.
+
+Compound index names must be a combination of field names separated by a #.
+Fields mentioned in the compound index name that aren't correctly annottated will result in a
+compilation error.
 
 ```rust
-use cryptonamo::Cryptonamo;
+use cryptonamo::Encryptable;
 
-#[derive(Cryptonamo)]
+#[derive(Debug, Encryptable)]
 struct User {
     #[cryptonamo(query = "exact", compound = "email#name")]
     #[partition_key]
     email: String,
-
+    
    #[cryptonamo(query = "prefix", compound = "email#name")]
     name: String,
 }
 ```
 
-**NOTE:** Compound indexes defined using the `compound` attribute are not currently working.
-Check out [SearchableRecord] for more information on how to implement compound indexes.
+It's also possible to add more than one query attribute to support querying records in multiple
+different ways.
+
 
-### Storing and Retrieving Records
+```rust
+use cryptonamo::Encryptable;
+
+#[derive(Debug, Encryptable)]
+struct User {
+    #[cryptonamo(query = "exact")]
+    #[cryptonamo(query = "exact", compound = "email#name")]
+    #[partition_key]
+    email: String,
+    
+   #[cryptonamo(query = "prefix")]
+   #[cryptonamo(query = "exact")]
+   #[cryptonamo(query = "prefix", compound = "email#name")]
+    name: String,
+}
+```
+It's important to note that the more annotations that are added to a field the more index terms that will be generated. Adding too many attributes could result in a
+proliferation of terms and data.
+
+###### Storing and Retrieving Records
 
 Interacting with a table in DynamoDB is done via the [EncryptedTable] struct.
 
@@ -220,48 +269,47 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     let client = aws_sdk_dynamodb::Client::new(&config);
     let table = EncryptedTable::init(client, "users").await?;
+
+    Ok(())
 }
 ```
 
 All operations on the table are `async` and so you will need a runtime to execute them.
 In the above example, we connect to a DynamoDB running in a local container and initialize an `EncryptedTable` struct
 for the "users" table.
 
-#### Putting Records
+####### Putting Records
 
 To store a record in the table, use the [`EncryptedTable::put`] method:
 
 ```rust
-#
 let user = User::new("dan@coderdan", "Dan Draper");
-table.put(&user).await?;
+table.put(user).await?;
 ```
 
 To get a record, use the [`EncryptedTable::get`] method:
 
 ```rust
-#
+
 let user: Option<User> = table.get("dan@coderdan.co").await?;
 ```
 
 The `get` method will return `None` if the record does not exist.
 It uses type information to decrypt the record and return it as a struct.
 
-#### Deleting Records
+####### Deleting Records
 
 To delete a record, use the [`EncryptedTable::delete`] method:
 
 ```rust
-#
 table.delete::<User>("jane@smith.org").await?;
 ```
 
-#### Querying Records
+####### Querying Records
 
 To query records, use the [`EncryptedTable::query`] method which returns a builder:
 
 ```rust
-#
 let results: Vec<User> = table
     .query()
     .starts_with("name", "Dan")
@@ -272,7 +320,6 @@ let results: Vec<User> = table
 If you have a compound index defined, Cryptonamo will automatically use it when querying.
 
 ```rust
-#
 let results: Vec<User> = table
     .query()
     .eq("email", "dan@coderdan")
@@ -281,17 +328,20 @@ let results: Vec<User> = table
     .await?;
 ```
 
-### Table Verticalization
+Note: if you don't have the correct indexes defined this query builder will return a runtime
+error.
+
+###### Table Verticalization
 
 Cryptonamo uses a technique called "verticalization" which is a popular approach to storing data in DynamoDB.
 In practice, this means you can store multiple types in the same table.
 
 For example, you might want to store related records to `User` such as `License`.
 
 ```rust
-use cryptonamo::Cryptonamo;
+use cryptonamo::{ Searchable, Encryptable, Decryptable };
 
-#[derive(Cryptonamo)]
+#[derive(Debug, Searchable, Encryptable, Decryptable)]
 struct License {
     #[cryptonamo(query = "exact")]
     #[partition_key]
@@ -305,18 +355,19 @@ struct License {
 }
 ```
 
-#### Data Views
+####### Data Views
 
 In some cases, these types might simply be a different representation of the same data based on query requirements.
 For example, you might want to query users by name using a prefix (say for using a "type ahead") but only return the name.
 
 ```rust
-#[derive(Cryptonamo)]
+
+#[derive(Debug, Searchable, Encryptable, Decryptable)]
 pub struct UserView {
     #[cryptonamo(skip)]
     #[partition_key]
     email: String,
-
+    
     #[cryptonamo(query = "prefix")]
     name: String,
 }
@@ -326,7 +377,7 @@ To use the view, you can first `put` and then `query` the value.
 
 ```rust
 let user = UserView::new("dan@coderdan", "Dan Draper");
-table.put(&user).await?;
+table.put(user).await?;
 let results: Vec<UserView> = table
     .query()
     .starts_with("name", "Dan")
@@ -336,13 +387,13 @@ let results: Vec<UserView> = table
 
 So long as the indexes are equivalent, you can mix and match types.
 
-### Internals
+###### Internals
 
-#### Table Schema
+####### Table Schema
 
 Tables created by Cryptonamo have the following schema:
 
-```rust
+```txt
 PK        |  SK           |  term                  |   name       |  email   ....
 ---------------------------------------------------------------------------
 HMAC(123) |  user         |                        |   Enc(name)  |  Enc(email)
@@ -358,7 +409,7 @@ HMAC(123) |  user#name#4  | STE("Mike R")          |
 And all other attributes are dependent on the type.
 They may be encrypted or otherwise.
 
-#### Source Encryption
+####### Source Encryption
 
 Cryptonamo uses the CipherStash SDK to encrypt and decrypt data.
 Values are encypted using a unique key for each record using AES-GCM-SIV with 256-bit keys.
@@ -368,9 +419,8 @@ ZeroKMS's root keys are encrypted using AWS KMS and stored in DynamoDB (separate
 
 When self-hosting ZeroKMS, we recommend running it in different account to your main application workloads.
 
-### Issues and TODO
+###### Issues and TODO
 
-- [ ] Support for plaintext types is currently not implemented
-- [ ] Using the derive macros for compound macros is not working correctly (you can implement the traits directly)
 - [ ] Sort keys are not currently hashed (and should be)
 
+<!-- cargo-rdme end -->