use serde::{Deserialize, Serialize};
use thiserror::Error;
#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize, Serialize)]
#[non_exhaustive]
#[serde(try_from = "u16", into = "u16")]
pub enum PluginProtocolVersion {
V1,
}
impl PluginProtocolVersion {
#[must_use]
pub const fn wire_value(self) -> u16 {
match self {
Self::V1 => 1,
}
}
}
impl From<PluginProtocolVersion> for u16 {
fn from(version: PluginProtocolVersion) -> Self {
version.wire_value()
}
}
impl TryFrom<u16> for PluginProtocolVersion {
type Error = UnsupportedPluginProtocolVersion;
fn try_from(version: u16) -> Result<Self, Self::Error> {
match version {
1 => Ok(Self::V1),
version => Err(UnsupportedPluginProtocolVersion { version }),
}
}
}
#[derive(Debug, Error)]
#[error("unsupported broker plugin protocol version {version}")]
pub struct UnsupportedPluginProtocolVersion {
version: u16,
}
impl UnsupportedPluginProtocolVersion {
#[must_use]
pub const fn version(&self) -> u16 {
self.version
}
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginHello {
pub protocol_version: PluginProtocolVersion,
pub plugin_id: String,
pub capabilities: Vec<crate::inspection::PluginCapability>,
}
impl PluginHello {
#[must_use]
pub fn new(plugin_id: String) -> Self {
Self {
protocol_version: PluginProtocolVersion::V1,
plugin_id,
capabilities: vec![crate::inspection::PluginCapability::AgentEvents],
}
}
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum PluginMessage {
PluginHello(PluginHello),
InspectResponse(crate::inspection::InspectResponse),
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum BrokerMessage {
BrokerHello(BrokerHello),
BrokerError(BrokerError),
BrokerClose(BrokerClose),
AgentEvent {
event: std::sync::Arc<crate::event::AgentEvent>,
},
InspectRequest {
context: std::sync::Arc<crate::inspection::AgentRequestContext>,
},
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct BrokerHello {
pub protocol_version: PluginProtocolVersion,
}
impl BrokerHello {
#[must_use]
pub const fn v1() -> Self {
Self {
protocol_version: PluginProtocolVersion::V1,
}
}
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct BrokerError {
pub code: u32,
pub reason: String,
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct BrokerClose {
pub code: u32,
pub reason: String,
}
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub enum BrokerErrorCode {
UnsupportedProtocolVersion,
InvalidHandshake,
ResourceLimit,
}
impl BrokerErrorCode {
#[must_use]
pub const fn wire_value(self) -> u32 {
match self {
Self::UnsupportedProtocolVersion => 1,
Self::InvalidHandshake => 2,
Self::ResourceLimit => 3,
}
}
}
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub enum BrokerCloseCode {
BrokerShutdown,
EventStreamTooSlow,
}
impl BrokerCloseCode {
#[must_use]
pub const fn wire_value(self) -> u32 {
match self {
Self::BrokerShutdown => 100,
Self::EventStreamTooSlow => 101,
}
}
}
impl BrokerError {
#[must_use]
pub fn new<T>(code: BrokerErrorCode, reason: T) -> Self
where
T: Into<String>,
{
Self {
code: code.wire_value(),
reason: reason.into(),
}
}
}
impl BrokerClose {
#[must_use]
pub fn new<T>(code: BrokerCloseCode, reason: T) -> Self
where
T: Into<String>,
{
Self {
code: code.wire_value(),
reason: reason.into(),
}
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::{
BrokerClose, BrokerError, BrokerHello, BrokerMessage, PluginHello, PluginMessage,
PluginProtocolVersion,
};
#[test]
fn unsupported_protocol_version_is_rejected() {
let error = serde_json::from_value::<PluginProtocolVersion>(json!(2_u16))
.expect_err("protocol version 2 must be rejected");
assert!(
error
.to_string()
.contains("unsupported broker plugin protocol version 2"),
"error should identify the unsupported protocol version"
);
}
#[test]
fn handshake_frames_have_explicit_tags() {
let plugin_hello = serde_json::to_value(PluginMessage::PluginHello(PluginHello::new(
"sample-plugin".to_owned(),
)))
.expect("plugin hello should serialize");
let broker_hello = serde_json::to_value(BrokerMessage::BrokerHello(BrokerHello::v1()))
.expect("broker hello should serialize");
assert_eq!(plugin_hello["type"], "plugin_hello");
assert_eq!(broker_hello["type"], "broker_hello");
assert_eq!(
plugin_hello["capabilities"],
serde_json::json!(["agent_events"])
);
assert_eq!(
plugin_hello["protocol_version"], 1_u16,
"hello must request v1"
);
assert_eq!(
plugin_hello["plugin_id"], "sample-plugin",
"plugin id must be stable"
);
assert_eq!(
broker_hello["protocol_version"], 1_u16,
"broker hello must confirm plugin protocol v1"
);
}
#[test]
fn broker_control_frames_have_explicit_tags() {
let broker_error = serde_json::to_value(BrokerMessage::BrokerError(BrokerError {
code: 1,
reason: "unsupported protocol version".to_owned(),
}))
.expect("broker error should serialize");
let broker_close = serde_json::to_value(BrokerMessage::BrokerClose(BrokerClose {
code: 101,
reason: "plugin event stream is too slow".to_owned(),
}))
.expect("broker close should serialize");
assert_eq!(broker_error["type"], "broker_error");
assert_eq!(broker_error["code"], 1_u32);
assert_eq!(broker_error["reason"], "unsupported protocol version");
assert_eq!(broker_close["type"], "broker_close");
assert_eq!(broker_close["code"], 101_u32);
assert_eq!(broker_close["reason"], "plugin event stream is too slow");
}
}