Skip to content

[nexus] Webhook API skeleton #7274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

[nexus] Webhook API skeleton #7274

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4118154
[nexus] Webhook API skeleton
hawkw Dec 12, 2024
bfb0c34
naming consistency edits from @augustuswm
hawkw Dec 18, 2024
f26b052
fix cargo workspace hack
hawkw Dec 19, 2024
3aee3cd
update to match RFD 538
hawkw Jan 2, 2025
b579475
also do event classes APIs
hawkw Jan 2, 2025
e2f3f2c
apparently this is also a thing we need to do
hawkw Jan 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 10 additions & 0 deletions nexus/external-api/output/nexus_tags.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,16 @@ API operations found with tag "system/status"
OPERATION ID METHOD URL PATH
ping GET /v1/ping

API operations found with tag "system/webhooks"
OPERATION ID METHOD URL PATH
webhook_create POST /experimental/v1/webhooks
webhook_delete DELETE /experimental/v1/webhooks/{webhook_id}
webhook_delivery_list GET /experimental/v1/webhooks/{webhook_id}/deliveries
webhook_delivery_resend POST /experimental/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/resend
webhook_secrets_add POST /experimental/v1/webhooks/{webhook_id}/secrets
webhook_secrets_list GET /experimental/v1/webhooks/{webhook_id}/secrets
webhook_view GET /experimental/v1/webhooks/{webhook_id}

API operations found with tag "vpcs"
OPERATION ID METHOD URL PATH
internet_gateway_create POST /v1/internet-gateways
Expand Down
87 changes: 87 additions & 0 deletions nexus/external-api/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,12 @@ pub const API_VERSION: &str = "20241204.0.0";
url = "http://docs.oxide.computer/api/vpcs"
}
},
"system/webhooks" = {
description = "Webhooks deliver notifications for audit log events and fault management alerts.",
external_docs = {
url = "http://docs.oxide.computer/api/webhooks"
}
},
"system/probes" = {
description = "Probes for testing network connectivity",
external_docs = {
Expand Down Expand Up @@ -3088,6 +3094,87 @@ pub trait NexusExternalApi {
rqctx: RequestContext<Self::Context>,
params: TypedBody<params::DeviceAccessTokenRequest>,
) -> Result<Response<Body>, HttpError>;

// Webhooks (experimental)

/// Get the configuration for a webhook.
#[endpoint {
method = GET,
path = "/experimental/v1/webhooks/{webhook_id}",
tags = ["system/webhooks"],
}]
async fn webhook_view(
rqctx: RequestContext<Self::Context>,
path_params: Path<params::WebhookPath>,
) -> Result<HttpResponseOk<views::Webhook>, HttpError>;

/// Create a new webhook receiver.
#[endpoint {
method = POST,
path = "/experimental/v1/webhooks",
tags = ["system/webhooks"],
}]
async fn webhook_create(
rqctx: RequestContext<Self::Context>,
params: TypedBody<params::WebhookCreate>,
) -> Result<HttpResponseCreated<views::Webhook>, HttpError>;

/// Delete a webhook receiver.
#[endpoint {
method = DELETE,
path = "/experimental/v1/webhooks/{webhook_id}",
tags = ["system/webhooks"],
}]
async fn webhook_delete(
rqctx: RequestContext<Self::Context>,
path_params: Path<params::WebhookPath>,
) -> Result<HttpResponseDeleted, HttpError>;

/// List the IDs of secrets for a webhook receiver.
#[endpoint {
method = GET,
path = "/experimental/v1/webhooks/{webhook_id}/secrets",
tags = ["system/webhooks"],
}]
async fn webhook_secrets_list(
rqctx: RequestContext<Self::Context>,
path_params: Path<params::WebhookPath>,
) -> Result<HttpResponseOk<views::WebhookSecrets>, HttpError>;

/// Add a secret to a webhook.
#[endpoint {
method = POST,
path = "/experimental/v1/webhooks/{webhook_id}/secrets",
tags = ["system/webhooks"],
}]
async fn webhook_secrets_add(
rqctx: RequestContext<Self::Context>,
path_params: Path<params::WebhookPath>,
params: TypedBody<params::WebhookSecret>,
) -> Result<HttpResponseCreated<views::WebhookSecretId>, HttpError>;

/// List delivery attempts to a webhook receiver.
#[endpoint {
method = GET,
path = "/experimental/v1/webhooks/{webhook_id}/deliveries",
tags = ["system/webhooks"],
}]
async fn webhook_delivery_list(
rqctx: RequestContext<Self::Context>,
path_params: Path<params::WebhookPath>,
query_params: Query<PaginatedById>,
) -> Result<HttpResponseOk<ResultsPage<views::WebhookDelivery>>, HttpError>;

/// Request re-delivery of a webhook event.
#[endpoint {
method = POST,
path = "/experimental/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/resend",
tags = ["system/webhooks"],
}]
async fn webhook_delivery_resend(
rqctx: RequestContext<Self::Context>,
path_params: Path<params::WebhookDeliveryPath>,
) -> Result<HttpResponseCreated<views::WebhookDeliveryId>, HttpError>;
}

/// Perform extra validations on the OpenAPI spec.
Expand Down
165 changes: 165 additions & 0 deletions nexus/src/external_api/http_entrypoints.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6298,4 +6298,169 @@ impl NexusExternalApi for NexusExternalApiImpl {
) -> Result<Response<Body>, HttpError> {
device_auth::device_access_token(rqctx, params.into_inner()).await
}

async fn webhook_view(
rqctx: RequestContext<Self::Context>,
_path_params: Path<params::WebhookPath>,
) -> Result<HttpResponseOk<views::Webhook>, HttpError> {
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}

async fn webhook_create(
rqctx: RequestContext<Self::Context>,
_params: TypedBody<params::WebhookCreate>,
) -> Result<HttpResponseCreated<views::Webhook>, HttpError> {
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}

async fn webhook_delete(
rqctx: RequestContext<Self::Context>,
_path_params: Path<params::WebhookPath>,
) -> Result<HttpResponseDeleted, HttpError> {
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}

async fn webhook_secrets_list(
rqctx: RequestContext<Self::Context>,
_path_params: Path<params::WebhookPath>,
) -> Result<HttpResponseOk<views::WebhookSecrets>, HttpError> {
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}

/// Add a secret to a webhook.
async fn webhook_secrets_add(
rqctx: RequestContext<Self::Context>,
_path_params: Path<params::WebhookPath>,
_params: TypedBody<params::WebhookSecret>,
) -> Result<HttpResponseCreated<views::WebhookSecretId>, HttpError> {
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}

async fn webhook_delivery_list(
rqctx: RequestContext<Self::Context>,
_path_params: Path<params::WebhookPath>,
_query_params: Query<PaginatedById>,
) -> Result<HttpResponseOk<ResultsPage<views::WebhookDelivery>>, HttpError>
{
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}

async fn webhook_delivery_resend(
rqctx: RequestContext<Self::Context>,
_path_params: Path<params::WebhookDeliveryPath>,
) -> Result<HttpResponseCreated<views::WebhookDeliveryId>, HttpError> {
let apictx = rqctx.context();
let handler = async {
let nexus = &apictx.context.nexus;

let opctx =
crate::context::op_context_for_external_api(&rqctx).await?;

Err(nexus
.unimplemented_todo(&opctx, crate::app::Unimpl::Public)
.await
.into())
};
apictx
.context
.external_latencies
.instrument_dropshot_handler(&rqctx, handler)
.await
}
}
3 changes: 2 additions & 1 deletion nexus/types/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ openssl.workspace = true
oxql-types.workspace = true
oxnet.workspace = true
parse-display.workspace = true
schemars = { workspace = true, features = ["chrono", "uuid1"] }
schemars = { workspace = true, features = ["chrono", "uuid1", "url"] }
serde.workspace = true
serde_json.workspace = true
serde_with.workspace = true
Expand All @@ -41,6 +41,7 @@ thiserror.workspace = true
newtype-uuid.workspace = true
update-engine.workspace = true
uuid.workspace = true
url = { workspace = true, features = ["serde"] }

api_identity.workspace = true
gateway-client.workspace = true
Expand Down
23 changes: 23 additions & 0 deletions nexus/types/src/external_api/params.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ use std::collections::BTreeMap;
use std::collections::BTreeSet;
use std::collections::HashMap;
use std::{net::IpAddr, str::FromStr};
use url::Url;
use uuid::Uuid;

macro_rules! path_param {
Expand Down Expand Up @@ -91,6 +92,7 @@ path_param!(ProbePath, probe, "probe");
path_param!(CertificatePath, certificate, "certificate");

id_path_param!(GroupPath, group_id, "group");
id_path_param!(WebhookPath, webhook_id, "webhook");

// TODO: The hardware resources should be represented by its UUID or a hardware
// ID that can be used to deterministically generate the UUID.
Expand Down Expand Up @@ -2277,3 +2279,24 @@ pub struct DeviceAccessTokenRequest {
pub device_code: String,
pub client_id: Uuid,
}

// Webhooks

#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
pub struct WebhookCreate {
pub name: String,
pub endpoint: Url,
pub secrets: Vec<String>,
pub events: Vec<String>,
}

#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
pub struct WebhookSecret {
pub secret: String,
}

#[derive(Deserialize, JsonSchema)]
pub struct WebhookDeliveryPath {
pub webhook_id: Uuid,
pub delivery_id: Uuid,
}
Loading
Loading