Update README#33
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a substantially expanded README for the alternator-driver crate, documenting terminology and intended usage patterns for an Alternator-compatible DynamoDB client in Rust.
Changes:
- Replaces the placeholder README with a full crate overview and glossary.
- Adds usage examples for configuring
AlternatorConfig/AlternatorClient. - Documents features such as load balancing, routing scope, key route affinity, header stripping, compression, and per-operation overrides.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Alternator accepts compressed request bodies, which can significantly reduce the bandwidth for write-heavy workloads (especially `BatchWriteItem` and large `PutItem` payloads). | ||
|
|
||
| Compression is **off by default**. To enable it, pass a `RequestCompression` configuration: | ||
|
|
||
| ```rust | ||
| use alternator_driver::{AlternatorConfig, AlternatorClient, RequestCompression, CompressionAlgorithm, CompressionLevel}; | ||
|
|
There was a problem hiding this comment.
Yes, and we decided to change it to be off by default, but this change isn't implemented yet. I will add a note about that.
There was a problem hiding this comment.
Maybe let's implement the change instead of leaving a note?
| ## Load balancing | ||
| > **Note:** load balancing is not yet merged, the changes described here are implemented in PRs #30, #31, and #32. |
There was a problem hiding this comment.
❓ Is it going to be merged before the ZPP finishes in late June?
There was a problem hiding this comment.
Leaving the PRs opened but unmerged is rarely a good option.
There was a problem hiding this comment.
Well, I hope so. Currently we are pretty much done discussing the changes, but since the move to scylladb org @m-szymon has lost the rights to merge.
There was a problem hiding this comment.
I can merge them whenever you decide it's the good moment to do so.
| Alternator accepts compressed request bodies, which can significantly reduce the bandwidth for write-heavy workloads (especially `BatchWriteItem` and large `PutItem` payloads). | ||
|
|
||
| Compression is **off by default**. To enable it, pass a `RequestCompression` configuration: | ||
|
|
||
| ```rust | ||
| use alternator_driver::{AlternatorConfig, AlternatorClient, RequestCompression, CompressionAlgorithm, CompressionLevel}; | ||
|
|
There was a problem hiding this comment.
Maybe let's implement the change instead of leaving a note?
| `.alternator_config_override()` is the Alternator-specific equivalent of the AWS SDK's `.config_override()`. The two work alongside each other — use `.config_override()` for SDK-level settings (retry behavior, timeouts) and `.alternator_config_override()` for Alternator-specific settings. | ||
|
|
||
| > **Note**: load-balancing and endpoint settings cannot be overridden per-operation. They take effect only when the client is constructed. Per-operation override is for settings that apply to individual request processing — compression and header stripping. No newline at end of file |
There was a problem hiding this comment.
💭 So AlternatorConfig may represent invalid state when used in alternator_config_override()? This is bad design. If some options make sense in only one of {alternator_config_override(), config_override()}, then they should accept distinct configs.
If you want to avoid code duplication when separating the configs, there are ways to do that - I suggest the typestate pattern. See GenericSessionBuilder in Rust Driver as a simplified example of this.
There was a problem hiding this comment.
I think README is a bit ambiguous, alternator_config_override is an extension of config_override.
Developer may keep config_override in their project or swap it with alternator_config_override for the same result. Swap is neccessary if they want to change an alternator-specific optimization like header stripping.
There was a problem hiding this comment.
Nonetheless, please confirm or correct my understanding:
AlternatorConfig may represent some settings that are only respected in alternator_config_override and not in config_override.
If the above is true, what I said still holds. Allowing user setting some options which are silently ignored is a footgun.
There was a problem hiding this comment.
AlternatorConfig cannot be passed into config_override(override : DynamodbConfig), only into alternator_config_override(override : AlternatorConfig).
AlternatorConfig stores an inner DynamodbConfig with all of DynamoDB's settings.
And alternator_config_override calls config_override with that inner config. (Also injecting alternator-specific optimizations to that config, before it is forwarded)
|
@lukaszg22 @wkkasztan please update README to include #34 and #32 (if not yet done). |
m-szymon
left a comment
m-szymon
left a comment
There was a problem hiding this comment.
@lukaszg22 please rebase it, squash commits (it is all a single update of README) and mark it as ready. I would like to merge this.
Add README. The glossary is mostly copied from the GoLang Alternator Client README.