platform/capabilities/src/http.rs

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

//! Host-authorized HTTP. Redirect and retry policy belongs to the plugin;
//! proxy configuration, bounded I/O and resource settlement belong to Host.

use crate::call::Scope;
use futures_util::future::BoxFuture;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Clone, Copy, Deserialize, Serialize)]
#[serde(rename_all = "UPPERCASE")]
pub enum Method {
    Get,
    Head,
    Post,
    Put,
    Patch,
    Delete,
    Options,
}

#[derive(Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct Request {
    pub url: String,
    pub method: Method,
    #[serde(default)]
    pub headers: Vec<(String, String)>,
    #[serde(default)]
    pub body: Vec<u8>,
}

#[derive(Serialize)]
pub struct Head {
    pub status: u16,
    pub url: String,
    /// Preserve duplicate headers and non-UTF-8 values.
    pub headers: Vec<(String, Vec<u8>)>,
}

pub struct Response {
    pub head: Head,
    pub body: Arc<dyn Body>,
}

pub trait Client: Send + Sync {
    fn request(&self, call: Scope, input: Request) -> BoxFuture<'_, Result<Response, Error>>;
}
pub trait Body: Send + Sync {
    /// One outstanding read; successful EOF confirms completion.
    fn next(&self) -> BoxFuture<'_, Result<Option<Vec<u8>>, Error>>;
    /// Signal before awaiting cleanup. Dropping the last body also cancels I/O.
    fn cancel(&self);
    fn close(&self) -> BoxFuture<'_, Result<(), Error>>;
}

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("HTTP call authority is retired or denied")]
    Denied,
    #[error("invalid HTTP request: {0}")]
    Invalid(String),
    #[error("HTTP operation failed; remote side effects may already have occurred: {0}")]
    Failed(String),
    #[error("HTTP resource cleanup is unconfirmed")]
    CleanupUnconfirmed,
}