[9/n] [dropshot] add API traits with support for endpoints#984
Merged
sunshowers merged 67 commits intoJul 3, 2024
Merged
Conversation
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
sunshowers
commented
Apr 29, 2024
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
sunshowers
commented
May 7, 2024
| //! for each type of response (which can also include documentation). This is | ||
| //! largely known statically, though generated at runtime. | ||
| //! | ||
| //! ### As a trait server |
Contributor
Author
There was a problem hiding this comment.
This is where the end-user documentation starts.
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
sunshowers
commented
May 20, 2024
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1
sunshowers
commented
Jun 11, 2024
Comment on lines
+1
to
+7
| error: endpoint `bad_endpoint` has invalid attributes: missing field `path` | ||
| --> tests/fail/bad_server_endpoint26.rs:12:1 | ||
| | | ||
| 12 | #[dropshot::server] | ||
| | ^^^^^^^^^^^^^^^^^^^ | ||
| | | ||
| = note: this error originates in the attribute macro `dropshot::server` (in Nightly builds, run with -Z macro-backtrace for more info) |
Contributor
Author
There was a problem hiding this comment.
This is addressed by oxidecomputer/serde_tokenstream#194.
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1 [skip ci]
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
ahl
approved these changes
Jun 12, 2024
ahl
left a comment
Collaborator
There was a problem hiding this comment.
I'd say I looked that code "some" i.e. in the places that I felt most familiar with. I scanned through the tests to think about coverage, and I looked at the docs for end-user clarity. If you'd like me to look more thoroughly at some part(s) please let me know but my general feeling is that the mechanics don't require intense scrutiny.
Comment on lines
+13
to
+17
| //! implementations to override the base behavior if desired (similar to std's | ||
| //! `Read` and `Write`). | ||
| //! * The behavior lives in a base trait, and the server is an extension trait | ||
| //! on top of it, with a blanket impl prohibiting overrides (similar to | ||
| //! tokio's `AsyncReadExt` and `AsyncWriteExt`). |
Collaborator
There was a problem hiding this comment.
I didn't follow the Read or AsyncReadExt analogies
Contributor
Author
There was a problem hiding this comment.
Expanded the doc comment to explain this in more detail.
Variations
The general degrees of freedom available when dealing with traits in Rust
are almost all available here. The main bit of flexibility that isn't
available is that server traits can't be object-safe.
Same trait with default methods
For example:
#[dropshot::server]
trait CounterServer {
type Context;
fn get_counter_impl(&self) -> impl Future<Output = u64> + Send;
fn set_counter_impl(
&self,
value: u64,
) -> impl Future<Output = Result<(), String>> + Send;
#[endpoint { method = GET, path = "/counter" }
async fn get_counter() {} // as below
#[endpoint { method = PUT, path = "/counter" }
async fn put_counter() {} // as below
}This is similar to how [std::io::Write]'s write_all method is defined as
a default method over the required write.
Supertrait
trait CounterBase {
fn get_counter_impl(&self) -> impl Future<Output = u64> + Send;
fn set_counter_impl(
&self,
value: u64,
) -> impl Future<Output = Result<(), String>> + Send;
}
#[dropshot::server]
trait CounterServer: CounterBase {
#[endpoint { method = GET, path = "/counter" }
async fn get_counter() {} // as below
#[endpoint { method = PUT, path = "/counter" }
async fn put_counter() {} // as below
}
// And optionally, a blanket impl.
impl<T: CounterBase> CounterServer for T {}With the optional blanket impl, implementations cannot override
CounterServer's behavior. This is similar to how
[tokio::io::AsyncWriteExt] has a blanket impl for
AsyncWrite.
| @@ -1,8 +1,15 @@ | |||
| // Copyright 2021 Oxide Computer Company | |||
| // | |||
| // Portions of this file are adapted from syn (https://github.com/dtolnay/syn), | |||
Contributor
Author
There was a problem hiding this comment.
I've added "adapted from syn" comments to the relevant bits (which is most of the file).
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
Created using spr 1.3.6-beta.1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
As discussed in RFD 479 and oxidecomputer/omicron#5247.
Add support for a new way to define Dropshot APIs: via a trait. This builds on work done in the prior PRs in this series, such that it reuses as much shared logic from endpoints as possible.
I've tried to structure the PR series such that this one is almost entirely added code. It's also mostly tests, with around 1400 lines of "real" code.
See RFD 479 for more information.
TODO