mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-20 08:01:46 +00:00
Keep direct aliases in v2 and update the SDK builder, runtime compatibility declaration, tests and migration guidance. BREAKING CHANGE: model_catalog plugins must declare version 2, move their alias list to aliases and return models for adapted models. Co-authored-by: Codex <noreply@openai.com>
580 lines
18 KiB
Rust
580 lines
18 KiB
Rust
//! 验证类型化插件处理器的组合注册、分派与能力声明一致性
|
|
|
|
mod outbound;
|
|
|
|
use std::{
|
|
collections::BTreeMap,
|
|
sync::{
|
|
Arc,
|
|
atomic::{AtomicUsize, Ordering},
|
|
},
|
|
time::Duration,
|
|
};
|
|
|
|
use gateway_plugin_sdk::{
|
|
CallContext, Contributions, ErrorCode, Frame, Handshake, Message, PROTOCOL_VERSION, Stage,
|
|
call::{
|
|
host::StateMigrationResult,
|
|
management::{
|
|
CommandDescriptor, CommandInvocation, CommandRegistration, CommandResult,
|
|
ManagementRegistration, ManagementRequest, ManagementResponse, ManagementRoute,
|
|
},
|
|
registration::Registration,
|
|
},
|
|
client::{
|
|
AuthorError, PluginBuilder, PluginHandler, PluginSession, SessionConfig, SessionError,
|
|
TypedReply, methods, read_frame, write_frame,
|
|
},
|
|
};
|
|
use serde_json::{Value, json};
|
|
use tokio::{
|
|
io::{DuplexStream, ReadHalf, WriteHalf},
|
|
task::JoinHandle,
|
|
};
|
|
|
|
const MAXIMUM_STREAM_CHUNK_BYTES: usize = 64 * 1024;
|
|
|
|
fn author_manifest(contributes: Value, state: Value) -> Vec<u8> {
|
|
serde_json::to_vec(&json!({
|
|
"manifestVersion":2,
|
|
"name": "composed",
|
|
"displayName": "Composed",
|
|
"publisher": "9acme",
|
|
"version": "1.0.0",
|
|
"description": "Composed plugin",
|
|
"license": "MIT",
|
|
"engines": {"codex-proxy-rs": "*"},
|
|
"main": "bin/plugin",
|
|
"runtime": "trustedProcess",
|
|
"contributes": contributes,
|
|
"state": state,
|
|
}))
|
|
.unwrap()
|
|
}
|
|
|
|
fn management_registration() -> ManagementRegistration {
|
|
ManagementRegistration {
|
|
routes: vec![ManagementRoute {
|
|
method: "POST".into(),
|
|
path: "echo".into(),
|
|
request_content_types: vec!["application/octet-stream".into()],
|
|
response_content_types: vec!["application/octet-stream".into()],
|
|
}],
|
|
resources: Vec::new(),
|
|
pages: Vec::new(),
|
|
callbacks: Vec::new(),
|
|
}
|
|
}
|
|
|
|
fn command_registration() -> CommandRegistration {
|
|
CommandRegistration {
|
|
commands: vec![CommandDescriptor {
|
|
name: "echo".into(),
|
|
description: "Echo a value".into(),
|
|
parameters: Vec::new(),
|
|
}],
|
|
}
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn composed_plugin_registers_and_dispatches_multiple_typed_entries() {
|
|
let source = author_manifest(
|
|
json!({
|
|
"management": {"version":2},
|
|
"command_line": {},
|
|
}),
|
|
json!([]),
|
|
);
|
|
let manifest = gateway_plugin_sdk::Manifest::from_author_slice(&source).unwrap();
|
|
let contributions = manifest.contributes.clone();
|
|
let management_calls = Arc::new(AtomicUsize::new(0));
|
|
let management_calls_for_handler = Arc::clone(&management_calls);
|
|
let plugin = PluginBuilder::from_manifest(manifest)
|
|
.unwrap()
|
|
.management(management_registration(), move |call| {
|
|
let management_calls = Arc::clone(&management_calls_for_handler);
|
|
async move {
|
|
management_calls.fetch_add(1, Ordering::Relaxed);
|
|
Ok(TypedReply::new(ManagementResponse {
|
|
headers: Vec::new(),
|
|
status: 201,
|
|
content_type: call
|
|
.request
|
|
.content_type
|
|
.unwrap_or_else(|| "application/octet-stream".into()),
|
|
})
|
|
.with_payload(call.payload))
|
|
}
|
|
})
|
|
.unwrap()
|
|
.command_line(command_registration(), |call| async move {
|
|
Ok(TypedReply::new(CommandResult {
|
|
stdout: call.request.name,
|
|
stderr: String::new(),
|
|
exit_code: 0,
|
|
accounts: Vec::new(),
|
|
}))
|
|
})
|
|
.unwrap()
|
|
.build()
|
|
.unwrap();
|
|
let (mut host, task) = start_session(plugin, contributions.clone()).await;
|
|
|
|
send_call(
|
|
&mut host,
|
|
1,
|
|
"plugin.register",
|
|
Stage::Registration,
|
|
json!({}),
|
|
Vec::new(),
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 1);
|
|
let registration: Registration = serde_json::from_value(result).unwrap();
|
|
assert_eq!(registration.contributes, contributions);
|
|
assert!(payload.is_empty());
|
|
|
|
send_call(
|
|
&mut host,
|
|
3,
|
|
"management.register",
|
|
Stage::Registration,
|
|
json!({}),
|
|
Vec::new(),
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 3);
|
|
assert_eq!(result, json!({}));
|
|
let registration: ManagementRegistration = serde_json::from_slice(&payload).unwrap();
|
|
assert_eq!(registration.routes.len(), 1);
|
|
assert_eq!(registration.routes[0].path, "echo");
|
|
|
|
send_call(
|
|
&mut host,
|
|
5,
|
|
"management.handle",
|
|
Stage::Management,
|
|
serde_json::to_value(ManagementRequest {
|
|
headers: Vec::new(),
|
|
method: "POST".into(),
|
|
path: "echo".into(),
|
|
query: String::new(),
|
|
content_type: Some("text/plain".into()),
|
|
})
|
|
.unwrap(),
|
|
b"typed body".to_vec(),
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 5);
|
|
let response: ManagementResponse = serde_json::from_value(result).unwrap();
|
|
assert_eq!(response.status, 201);
|
|
assert_eq!(response.content_type, "text/plain");
|
|
assert_eq!(payload, b"typed body");
|
|
assert_eq!(management_calls.load(Ordering::Relaxed), 1);
|
|
|
|
send_call(
|
|
&mut host,
|
|
7,
|
|
"command_line.register",
|
|
Stage::Registration,
|
|
json!({}),
|
|
Vec::new(),
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 7);
|
|
assert_eq!(result, json!({}));
|
|
let registration: CommandRegistration = serde_json::from_slice(&payload).unwrap();
|
|
assert_eq!(registration.commands.len(), 1);
|
|
assert_eq!(registration.commands[0].name, "echo");
|
|
|
|
let invocation = CommandInvocation {
|
|
name: "echo".into(),
|
|
arguments: BTreeMap::new(),
|
|
};
|
|
send_call(
|
|
&mut host,
|
|
9,
|
|
"command_line.execute",
|
|
Stage::CommandLine,
|
|
json!({}),
|
|
serde_json::to_vec(&invocation).unwrap(),
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 9);
|
|
assert_eq!(result, json!({}));
|
|
let output: CommandResult = serde_json::from_slice(&payload).unwrap();
|
|
assert_eq!(output.stdout, "echo");
|
|
assert_eq!(output.exit_code, 0);
|
|
|
|
shutdown(&mut host, task).await;
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn catalog_and_retry_entries_use_typed_registration_and_stage_validation() {
|
|
use gateway_plugin_sdk::call::{
|
|
catalog::{AdaptedModel, ModelAlias, ModelCatalogRegistrationV2, ModelPresentation},
|
|
policy::{RetryAction, RetryDecision, RetryDecisionRequest},
|
|
};
|
|
let source = author_manifest(
|
|
json!({"model_catalog":{"version":2},"retry_policy":{"version":2}}),
|
|
json!([]),
|
|
);
|
|
let manifest = gateway_plugin_sdk::Manifest::from_author_slice(&source).unwrap();
|
|
let contributions = manifest.contributes.clone();
|
|
let catalog = ModelCatalogRegistrationV2 {
|
|
aliases: vec![ModelAlias {
|
|
id: "public-model".into(),
|
|
provider: "openai".into(),
|
|
model: "upstream-model".into(),
|
|
}],
|
|
models: vec![AdaptedModel {
|
|
id: "adapted-model".into(),
|
|
adapter_id: "example".into(),
|
|
features: vec![],
|
|
max_output_tokens: None,
|
|
presentation: ModelPresentation::default(),
|
|
}],
|
|
};
|
|
let plugin = PluginBuilder::from_manifest(manifest)
|
|
.unwrap()
|
|
.model_catalog(catalog.clone())
|
|
.unwrap()
|
|
.on(methods::RETRY_DECISION, |call| async move {
|
|
Ok(TypedReply::new(
|
|
if call.request.allowed_actions.contains(&RetryAction::Retry) {
|
|
RetryDecision::Retry
|
|
} else {
|
|
RetryDecision::Delegate
|
|
},
|
|
))
|
|
})
|
|
.unwrap()
|
|
.build()
|
|
.unwrap();
|
|
let (mut host, task) = start_session(plugin, contributions).await;
|
|
send_call(
|
|
&mut host,
|
|
1,
|
|
"model_catalog.register",
|
|
Stage::Registration,
|
|
json!({}),
|
|
vec![],
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 1);
|
|
assert_eq!(result, json!({}));
|
|
assert_eq!(
|
|
serde_json::from_slice::<ModelCatalogRegistrationV2>(&payload).unwrap(),
|
|
catalog
|
|
);
|
|
let request = serde_json::to_value(RetryDecisionRequest {
|
|
request_id: "req-example".into(),
|
|
attempt_index: 1,
|
|
provider: "openai".into(),
|
|
model: Some("upstream-model".into()),
|
|
error_kind: "rate_limited".into(),
|
|
upstream_status: Some(429),
|
|
send_state: gateway_plugin_sdk::SendState::NotSent,
|
|
remaining_routing_attempts: 1,
|
|
remaining_deadline_ms: 1_000,
|
|
allowed_actions: vec![RetryAction::Stop, RetryAction::Retry],
|
|
})
|
|
.unwrap();
|
|
send_call(
|
|
&mut host,
|
|
3,
|
|
"policy.retry_decision",
|
|
Stage::Request,
|
|
request.clone(),
|
|
vec![],
|
|
)
|
|
.await;
|
|
assert_invalid_input(receive(&mut host).await, 3);
|
|
send_call(
|
|
&mut host,
|
|
5,
|
|
"policy.retry_decision",
|
|
Stage::Retry,
|
|
request,
|
|
vec![],
|
|
)
|
|
.await;
|
|
let (result, payload) = unwrap_result(receive(&mut host).await, 5);
|
|
assert_eq!(result, json!({"decision":"retry"}));
|
|
assert!(payload.is_empty());
|
|
shutdown(&mut host, task).await;
|
|
}
|
|
|
|
#[tokio::test]
|
|
async fn typed_dispatch_rejects_wrong_stage_and_payload_shape_before_handler() {
|
|
let source = author_manifest(json!({"command_line": {}}), json!([]));
|
|
let manifest = gateway_plugin_sdk::Manifest::from_author_slice(&source).unwrap();
|
|
let contributions = manifest.contributes.clone();
|
|
let calls = Arc::new(AtomicUsize::new(0));
|
|
let calls_for_handler = Arc::clone(&calls);
|
|
let plugin = PluginBuilder::from_manifest(manifest)
|
|
.unwrap()
|
|
.command_line(command_registration(), move |_| {
|
|
let calls = Arc::clone(&calls_for_handler);
|
|
async move {
|
|
calls.fetch_add(1, Ordering::Relaxed);
|
|
Ok(TypedReply::new(CommandResult {
|
|
stdout: String::new(),
|
|
stderr: String::new(),
|
|
exit_code: 0,
|
|
accounts: Vec::new(),
|
|
}))
|
|
}
|
|
})
|
|
.unwrap()
|
|
.build()
|
|
.unwrap();
|
|
let (mut host, task) = start_session(plugin, contributions).await;
|
|
let invocation = serde_json::to_vec(&CommandInvocation {
|
|
name: "echo".into(),
|
|
arguments: BTreeMap::new(),
|
|
})
|
|
.unwrap();
|
|
|
|
send_call(
|
|
&mut host,
|
|
1,
|
|
"command_line.execute",
|
|
Stage::Management,
|
|
json!({}),
|
|
invocation.clone(),
|
|
)
|
|
.await;
|
|
assert_invalid_input(receive(&mut host).await, 1);
|
|
|
|
send_call(
|
|
&mut host,
|
|
3,
|
|
"command_line.execute",
|
|
Stage::CommandLine,
|
|
json!({"name": "must-not-be-control-metadata"}),
|
|
invocation,
|
|
)
|
|
.await;
|
|
assert_invalid_input(receive(&mut host).await, 3);
|
|
|
|
send_call(
|
|
&mut host,
|
|
5,
|
|
"command_line.execute",
|
|
Stage::CommandLine,
|
|
json!({}),
|
|
b"not json".to_vec(),
|
|
)
|
|
.await;
|
|
assert_invalid_input(receive(&mut host).await, 5);
|
|
assert_eq!(calls.load(Ordering::Relaxed), 0);
|
|
|
|
shutdown(&mut host, task).await;
|
|
}
|
|
|
|
#[test]
|
|
fn build_reports_missing_declared_handler() {
|
|
let source = author_manifest(json!({"management": {"version":2}}), json!([]));
|
|
let result = PluginBuilder::from_json(&source).unwrap().build();
|
|
assert!(matches!(
|
|
result,
|
|
Err(AuthorError::MissingMethod("management.register"))
|
|
));
|
|
}
|
|
|
|
#[test]
|
|
fn state_migration_is_a_base_method_gated_by_the_state_declaration() {
|
|
let state = json!([{
|
|
"namespace": "documents",
|
|
"schemaVersion": 2,
|
|
"schema": {"type": "object"},
|
|
"maximumRecords": 16,
|
|
"maximumBytes": 4096,
|
|
"maximumValueBytes": 1024,
|
|
"migratesFrom": [1]
|
|
}]);
|
|
let source = author_manifest(json!({}), state);
|
|
let missing = PluginBuilder::from_json(&source).unwrap().build();
|
|
assert!(matches!(
|
|
missing,
|
|
Err(AuthorError::MissingMethod("plugin.state.migrate"))
|
|
));
|
|
|
|
let plugin = PluginBuilder::from_json(&source)
|
|
.unwrap()
|
|
.on(methods::STATE_MIGRATE, |_| async {
|
|
Ok(TypedReply::new(StateMigrationResult {
|
|
changes: Vec::new(),
|
|
}))
|
|
})
|
|
.unwrap()
|
|
.build();
|
|
assert!(plugin.is_ok());
|
|
|
|
let source_without_migration = author_manifest(json!({}), json!([]));
|
|
let undeclared = PluginBuilder::from_json(&source_without_migration)
|
|
.unwrap()
|
|
.on(methods::STATE_MIGRATE, |_| async {
|
|
Ok(TypedReply::new(StateMigrationResult {
|
|
changes: Vec::new(),
|
|
}))
|
|
});
|
|
assert!(matches!(
|
|
undeclared,
|
|
Err(AuthorError::Method("plugin.state.migrate"))
|
|
));
|
|
}
|
|
|
|
struct HostPeer {
|
|
reader: ReadHalf<DuplexStream>,
|
|
writer: WriteHalf<DuplexStream>,
|
|
}
|
|
|
|
async fn start_session<H: PluginHandler + 'static>(
|
|
handler: H,
|
|
contributes: Contributions,
|
|
) -> (HostPeer, JoinHandle<Result<(), SessionError>>) {
|
|
let (host, plugin) = tokio::io::duplex(MAXIMUM_STREAM_CHUNK_BYTES * 2);
|
|
let (plugin_reader, plugin_writer) = tokio::io::split(plugin);
|
|
let task = tokio::spawn(async move {
|
|
PluginSession::accept(
|
|
plugin_reader,
|
|
plugin_writer,
|
|
SessionConfig {
|
|
maximum_stream_chunk_bytes: MAXIMUM_STREAM_CHUNK_BYTES,
|
|
maximum_calls: 4,
|
|
maximum_callbacks: 4,
|
|
maximum_buffered_stream_chunks: 16,
|
|
handshake_timeout: Duration::from_secs(1),
|
|
},
|
|
)
|
|
.await?
|
|
.run(handler)
|
|
.await
|
|
});
|
|
let (mut reader, mut writer) = tokio::io::split(host);
|
|
write_frame(
|
|
&mut writer,
|
|
&Frame::control(Message::Hello {
|
|
handshake: Handshake {
|
|
protocol_version: PROTOCOL_VERSION,
|
|
artifact_sha256: "a".repeat(64),
|
|
plugin_id: "9acme.composed".into(),
|
|
instance_id: "test-instance".into(),
|
|
generation: 1,
|
|
incarnation: "test-incarnation".into(),
|
|
configuration: json!({}),
|
|
|
|
contributes,
|
|
},
|
|
}),
|
|
)
|
|
.await
|
|
.unwrap();
|
|
let ready = read_frame(&mut reader).await.unwrap();
|
|
assert!(matches!(
|
|
ready,
|
|
Frame {
|
|
message: Message::Ready {
|
|
protocol_version: PROTOCOL_VERSION,
|
|
ref incarnation,
|
|
..
|
|
},
|
|
ref payload,
|
|
} if incarnation == "test-incarnation" && payload.is_empty()
|
|
));
|
|
(HostPeer { reader, writer }, task)
|
|
}
|
|
|
|
async fn send_call(
|
|
host: &mut HostPeer,
|
|
id: u64,
|
|
method: &str,
|
|
stage: Stage,
|
|
params: Value,
|
|
payload: Vec<u8>,
|
|
) {
|
|
write_frame(
|
|
&mut host.writer,
|
|
&Frame {
|
|
message: Message::Call {
|
|
id,
|
|
method: method.into(),
|
|
context: CallContext {
|
|
request: None,
|
|
call_id: id,
|
|
instance_id: "test-instance".into(),
|
|
generation: 1,
|
|
incarnation: "test-incarnation".into(),
|
|
stage,
|
|
timeout_ms: 1_000,
|
|
resource_stream: false,
|
|
resource_scope_id: format!("scope-{id}"),
|
|
request_id: None,
|
|
attempt_id: None,
|
|
account_id: None,
|
|
credential_revision: None,
|
|
},
|
|
params,
|
|
},
|
|
payload,
|
|
},
|
|
)
|
|
.await
|
|
.unwrap();
|
|
}
|
|
|
|
async fn receive(host: &mut HostPeer) -> Frame {
|
|
tokio::time::timeout(Duration::from_secs(1), async {
|
|
loop {
|
|
let frame = read_frame(&mut host.reader).await?;
|
|
match frame.message {
|
|
Message::Suspend { .. } | Message::CallbackConsumed { .. } => {}
|
|
Message::Resume { id, epoch } => {
|
|
write_frame(
|
|
&mut host.writer,
|
|
&Frame::control(Message::Resumed { id, epoch }),
|
|
)
|
|
.await?;
|
|
}
|
|
_ => return Ok::<_, gateway_plugin_sdk::FrameError>(frame),
|
|
}
|
|
}
|
|
})
|
|
.await
|
|
.expect("plugin response timed out")
|
|
.expect("plugin response frame must be valid")
|
|
}
|
|
|
|
fn unwrap_result(frame: Frame, expected_id: u64) -> (Value, Vec<u8>) {
|
|
match frame {
|
|
Frame {
|
|
message: Message::Result { id, result },
|
|
payload,
|
|
} if id == expected_id => (result, payload),
|
|
unexpected => panic!("unexpected plugin response: {unexpected:?}"),
|
|
}
|
|
}
|
|
|
|
fn assert_invalid_input(frame: Frame, expected_id: u64) {
|
|
assert!(matches!(
|
|
frame,
|
|
Frame {
|
|
message: Message::Error { id, error },
|
|
ref payload,
|
|
} if id == expected_id && error.code == ErrorCode::InvalidInput && payload.is_empty()
|
|
));
|
|
}
|
|
|
|
async fn shutdown(host: &mut HostPeer, task: JoinHandle<Result<(), SessionError>>) {
|
|
write_frame(&mut host.writer, &Frame::control(Message::Shutdown))
|
|
.await
|
|
.unwrap();
|
|
tokio::time::timeout(Duration::from_secs(1), task)
|
|
.await
|
|
.expect("plugin session did not shut down")
|
|
.expect("plugin session task panicked")
|
|
.expect("plugin session shutdown failed");
|
|
}
|