Lib.rs

Dropshot 是一个通用但具有特定观点的 crate，用于从 Rust 程序中暴露 REST API。它旨在简单轻量。它包括对 OpenAPI 的一等支持，以精确的规格形式直接从代码生成。这是因为它服务的 HTTP 资源的函数消耗特定类型的参数并返回特定类型的值，从而可以静态生成模式。

有关配置、设计和贡献的信息，请参阅 GitHub 仓库。

有关 API 的使用信息，请参阅 文档。

lib.rs:

Dropshot 是一个用于从 Rust 程序中暴露 REST API 的通用 crate。计划中的亮点包括

• 适用于在基本不可信的网络上进行生产使用的适用性。基于 Dropshot 的系统应该是高性能的、可靠的、可调试的，并且能够抵御基本拒绝服务攻击（无论是有意的还是无意的）。

• 一等 OpenAPI 支持，以精确的 OpenAPI 规范形式直接从代码生成。这是因为它服务的 HTTP 资源的函数消耗特定类型的参数并返回特定类型的值，从而可以静态生成模式。

• 易于融入多元化的团队。Dropshot消费者的重要用例是拥有一个工程师团队，其中个人可以一次性向复杂的服务器添加几个端点，并且这样做应该是相对容易的。这意味着我们需要强调最小意外原则：就像Rust本身一样，我们可能会选择需要更多时间来学习的前期抽象，以便更难意外构建不会运行、在边缘情况下崩溃的系统等。

当我们提到“REST API”时，我们主要指的是基于现有HTTP原语构建的API，组织成分层资源，并提供了创建、更新、列出和删除这些资源的连续、幂等的机制。“REST”可以根据你与谁交谈而意味着不同的事情，有些人对什么是或不是RESTy非常教条。我们发现这种教条不仅无助于解决问题，而且定义不清。（考虑这样一个简单的情况，即尝试在REST API中更新资源。流行的API有时使用PUT、PATCH或POST作为动词；以及JSON Merge Patch或JSON Patch作为格式。（有时甚至不知道自己在做什么！）几乎没有任何明确的标准，但这对于任何REST API来说都是一个真正的基本操作。）

有关考虑的替代crate的讨论，请参阅Oxide RFD 10。

我们希望Dropshot相当通用，但它的主要目的是满足Oxide控制平面的需求。

用法

最基本的情况可能如下所示

use dropshot::ApiDescription;
use dropshot::ConfigDropshot;
use dropshot::ConfigLogging;
use dropshot::ConfigLoggingLevel;
use dropshot::HandlerTaskMode;
use dropshot::HttpServerStarter;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), String> {
    // Set up a logger.
    let log =
        ConfigLogging::StderrTerminal {
            level: ConfigLoggingLevel::Info,
        }
        .to_logger("minimal-example")
        .map_err(|e| e.to_string())?;

    // Describe the API.
    let api = ApiDescription::new();
    // Register API functions -- see detailed example or ApiDescription docs.

    // Start the server.
    let server =
        HttpServerStarter::new(
            &ConfigDropshot {
                bind_address: "127.0.0.1:0".parse().unwrap(),
                request_body_max_bytes: 1024,
                default_handler_task_mode: HandlerTaskMode::Detached,
                log_headers: Default::default(),
            },
            api,
            Arc::new(()),
            &log,
        )
        .map_err(|error| format!("failed to start server: {}", error))?
        .start();

    server.await
}

此服务器对所有资源返回404，因为没有注册API函数。有关使用共享状态提供一些资源的简单、文档化示例，请参阅examples/basic.rs。

API处理函数

HTTP讨论的是资源。对于REST API，我们经常讨论端点或操作，它们由HTTP方法和URI路径的组合来识别。

名为“项目”的资源的一些示例端点可能包括

• GET /projects（列出项目）
• POST /projects（创建项目的一种方式）
• GET /projects/my_project（获取一个项目）
• PUT /projects/my_project（更新（或可能创建）一个项目）
• DELETE /projects/my_project（删除一个项目）

在Dropshot中，对给定API端点的请求由特定的Rust函数处理。该函数被称为入口点、端点处理程序或处理函数。当你设置Dropshot服务器时，你通过设置一个ApiDescription来配置可用的API端点以及哪个函数将处理每一个。

定义一组端点有两种方式

作为自由函数

最简单的Dropshot服务器将端点定义为函数，用endpoint宏进行注释。以下是一个列出硬编码项目的单个端点的示例

use dropshot::endpoint;
use dropshot::ApiDescription;
use dropshot::HttpError;
use dropshot::HttpResponseOk;
use dropshot::RequestContext;
use http::Method;
use schemars::JsonSchema;
use serde::Serialize;
use std::sync::Arc;

/// Represents a project in our API.
#[derive(Serialize, JsonSchema)]
struct Project {
    /// Name of the project.
    name: String,
}

/// Fetch a project.
#[endpoint {
    method = GET,
    path = "/projects/project1",
}]
async fn myapi_projects_get_project(
    rqctx: RequestContext<()>,
) -> Result<HttpResponseOk<Project>, HttpError>
{
   let project = Project { name: String::from("project1") };
   Ok(HttpResponseOk(project))
}

fn main() {
    let mut api = ApiDescription::new();

    // Register our endpoint and its handler function.  The "endpoint" macro
    // specifies the HTTP method and URI path that identify the endpoint,
    // allowing this metadata to live right alongside the handler function.
    api.register(myapi_projects_get_project).unwrap();

    // ... (use `api` to set up an `HttpServer` )
}

这里有很多事情要处理

• endpoint宏指定了HTTP方法和URI路径。当我们调用ApiDescription::register()时，这些信息被用来注册我们的函数将处理的端点。
• 我们函数的签名表明，在成功的情况下，它返回一个HttpResponseOk<Project>。这意味着该函数将返回一个HTTP 200状态码（"OK"）和一个类型为Project的对象。
• 函数本身有一个Rustdoc注释，它将被用来在OpenAPI模式中记录这个端点。

根据这些信息，Dropshot可以生成一个描述此API的OpenAPI规范，该规范描述了端点（OpenAPI称为"操作"），其文档，它可以返回的可能响应，以及每种响应类型的模式（这也可以包括文档）。这主要是静态的，但在运行时生成。

作为API特质

API特质是一个Rust特质，它代表了一组API端点。每个端点被定义为特质上的一个静态方法，整个特质用#[dropshot::api_description]进行注解。（需要Rust 1.75或更高版本。）

与基于函数的服务器相比，API特质将接口定义与实现分离。将定义和实现保存在不同的crate中可以允许更快地迭代接口，并且简化了使用从接口的OpenAPI输出生成的客户端的多服务仓库。此外，API特质允许有多个实现，例如用于测试的模拟实现。

以下是一个与上述基于函数的服务器等效的API特质的示例

use dropshot::ApiDescription;
use dropshot::HttpError;
use dropshot::HttpResponseOk;
use dropshot::RequestContext;
use http::Method;
use schemars::JsonSchema;
use serde::Serialize;
use std::sync::Arc;

/// Represents a project in our API.
#[derive(Serialize, JsonSchema)]
struct Project {
    /// Name of the project.
    name: String,
}

/// Defines the trait that captures all the methods.
#[dropshot::api_description]
trait ProjectApi {
    /// The context type used within endpoints.
    type Context;

    /// Fetch a project.
    #[endpoint {
        method = GET,
        path = "/projects/project1",
    }]
    async fn myapi_projects_get_project(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<Project>, HttpError>;
}

// The `dropshot::api_description` macro generates a module called
// `project_api_mod`. This module has a method called `api_description`
// that, given an implementation of the trait, returns an `ApiDescription`.
// The `ApiDescription` can then be used to set up an `HttpServer`.

// --- The following code may be in another crate ---

/// An empty type to hold the project server context.
///
/// This type is never constructed, and is purely a way to name
/// the specific server impl.
enum ServerImpl {}

impl ProjectApi for ServerImpl {
    type Context = ();

    async fn myapi_projects_get_project(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<Project>, HttpError> {
        let project = Project { name: String::from("project1") };
        Ok(HttpResponseOk(project))
    }
}

fn main() {
    // The type of `api` is provided for clarity -- it is generally inferred.
    // "api" will automatically register all endpoints defined in the trait.
    let mut api: ApiDescription<()> =
        project_api_mod::api_description::<ServerImpl>().unwrap();

    // ... (use `api` to set up an `HttpServer` )
}

请参阅api-trait.rs和api-trait-alternate.rs以获取有效示例。

限制

目前，#[dropshot::api_description]宏仅在模块上下文中受支持，不在函数体内。这是一个Rust限制——有关更多详细信息，请参阅Rust问题#79260。

选择函数和特质之间的区别

原型设计：如果您正在使用少量端点进行原型设计，函数提供了一种更简单的方法来开始。特质的不利之处在于，端点签名至少定义了两次，一次在特质中，一次在实现中。

小型服务：对于相对隔离且编译快速的服务，特性和函数都是不错的选择。

具有多个实现的API：对于足够大以至于有第二个更简单的实现（可能只是部分）的服务，特质是最佳选择。

#[endpoint { ... }]属性参数

endpoint属性接受影响端点操作的参数以及出现在OpenAPI描述中的元数据。

#[endpoint {
    // Required fields
    method = { DELETE | HEAD | GET | OPTIONS | PATCH | POST | PUT },
    path = "/path/name/with/{named}/{variables}",

    // Optional fields
    tags = [ "all", "your", "OpenAPI", "tags" ],
}]

您在这里指定API端点的HTTP方法和路径（包括路径变量）。这些用于端点注册的一部分，并出现在OpenAPI规范输出中。

tags字段用于对API端点进行分类，并且仅影响OpenAPI规范输出。

函数参数

通常，处理函数看起来像这样

async fn f(
     rqctx: RequestContext<Context>,
     [query_params: Query<Q>,]
     [path_params: Path<P>,]
     [body_param: TypedBody<J>,]
     [body_param: UntypedBody,]
     [body_param: StreamingBody,]
     [raw_request: RawRequest,]
) -> Result<HttpResponse*, HttpError>

RequestContext必须首先出现。类型Context是调用者提供的上下文，它在创建服务器时提供。

类型 Query、Path、TypedBody、UntypedBody 和 RawRequest 被称为 提取器，因为它们会将信息从请求中提取出来，使其可用于处理函数。

• Query<Q> 从查询字符串中提取参数，将其反序列化为类型 Q 的实例。类型 Q 必须实现 serde::Deserialize 和 schemars::JsonSchema。
• Path<P> 从 HTTP 路径中提取参数，将其反序列化为类型 P 的实例。类型 P 必须实现 serde::Deserialize 和 schemars::JsonSchema。
• TypedBody<J> 通过将请求体解析为 JSON（或表单/url 编码）并反序列化为类型 J 的实例来提取请求体内容。类型 J 必须实现 serde::Deserialize 和 schemars::JsonSchema。
• UntypedBody 提取请求体的原始字节。
• StreamingBody 将请求体的原始字节作为 Stream 的 Bytes 块提供。
• RawRequest 提供对底层 hyper::Request 的访问。希望这通常不需要。它对于实现 Dropshot 不提供的功能可能很有用。

use http::StatusCode;
use dropshot::HttpError;
use dropshot::TypedBody;
use dropshot::Query;
use dropshot::RequestContext;
use hyper::Body;
use hyper::Response;
use schemars::JsonSchema;
use serde::Deserialize;
use std::sync::Arc;

#[derive(Deserialize, JsonSchema)]
struct MyQueryArgs {
    limit: u32,
    marker: Option<String>
}

struct MyContext {}

async fn myapi_projects_get(
    rqctx: RequestContext<MyContext>,
    query: Query<MyQueryArgs>)
    -> Result<Response<Body>, HttpError>
{
    let query_args = query.into_inner();
    let context: &MyContext = rqctx.context();
    let limit: u32 = query_args.limit;
    let marker: Option<String> = query_args.marker;
    Ok(Response::builder()
        .status(StatusCode::OK)
        .body(format!("limit = {}, marker = {:?}\n", limit, marker).into())?)
}

#
/// This is the API trait defined above.
#[dropshot::api_description]
trait ProjectApi {
    type Context;
    #[endpoint {
        method = GET,
        path = "/projects/project1",
    }]
    async fn myapi_projects_get_project(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<Project>, HttpError>;
}

let description = project_api_mod::stub_api_description().unwrap();
let mut openapi = description.openapi("Project Server", "1.0.0");
openapi.write(&mut std::io::stdout().lock()).unwrap();

{
    "name": "aardvark",
    "class": "mammal",
    "max_weight": "80", /* kilograms, typical */
}

{
    "next_page": "abc123...",
    "items": [
        {
            "name": "aardvark",
            "class": "mammal",
            "max_weight": "80",
        },
        ...
        {
            "name": "badger",
            "class": "mammal",
            "max_weight": "12",
        }
    ]
}

use dropshot::HttpError;
use dropshot::HttpResponseOk;
use dropshot::PaginationParams;
use dropshot::Query;
use dropshot::RequestContext;
use dropshot::ResultsPage;
use dropshot::endpoint;
use schemars::JsonSchema;
use serde::Deserialize;
use std::sync::Arc;
#[derive(Deserialize, JsonSchema)]
struct MyExtraQueryParams {
    do_extra_stuff: bool,
}

#[endpoint {
    method = GET,
    path = "/list_stuff"
}]
async fn my_list_api(
    rqctx: RequestContext<()>,
    pag_params: Query<PaginationParams<MyScanParams, MyPageSelector>>,
    extra_params: Query<MyExtraQueryParams>,
) -> Result<HttpResponseOk<ResultsPage<String>>, HttpError>
{
 # unimplemented!();
 /* ... */
}

{
    "required": [ .. ]
}

$ cargo +nightly run --example basic --features usdt-probes

## dtrace -Zq -n 'dropshot*:::request-* { printf("%s\n", copyinstr(arg0)); }'
{"ok":{"id":"b793c62e-60e4-45c5-9274-198a04d9abb1","local_addr":"127.0.0.1:61028","remote_addr":"127.0.0.1:34286","method":"GET","path":"/counter","query":null}}
{"ok":{"id":"b793c62e-60e4-45c5-9274-198a04d9abb1","local_addr":"127.0.0.1:61028","remote_addr":"127.0.0.1:34286","status_code":200,"message":""}}
{"ok":{"id":"9050e30a-1ce3-4d6f-be1c-69a11c618800","local_addr":"127.0.0.1:61028","remote_addr":"127.0.0.1:41101","method":"PUT","path":"/counter","query":null}}
{"ok":{"id":"9050e30a-1ce3-4d6f-be1c-69a11c618800","local_addr":"127.0.0.1:61028","remote_addr":"127.0.0.1:41101","status_code":400,"message":"do not like the number 10"}}
{"ok":{"id":"a53696af-543d-452f-81b6-5a045dd9921d","local_addr":"127.0.0.1:61028","remote_addr":"127.0.0.1:57376","method":"PUT","path":"/counter","query":null}}
{"ok":{"id":"a53696af-543d-452f-81b6-5a045dd9921d","local_addr":"127.0.0.1:61028","remote_addr":"127.0.0.1:57376","status_code":204,"message":""}}