25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
//! Shared desktop/Web orchestration, adapted from Ziyu Yang's PL/SQL debugger.
//! Native state stays in the Agent; Core retains intent and the original channel.
use std::collections::HashMap;
use std::sync::{Arc, Mutex, MutexGuard, Weak};
use std::time::{Duration, Instant};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use tokio::sync::Notify;
use uuid::Uuid;
use crate::agent_connection::{agent_connect_params_with_role, AgentSessionRole};
use crate::backend_error::BackendError;
use crate::connection::session_credentials::{current_credential_owner, with_credential_owner};
use crate::connection::{
agent_connect_timeout, AppState, ConnectionLifecycleSnapshot, ConnectionTransportPlan, ConnectionTransportStamp,
};
use crate::db::agent_driver::{AgentCallError, AgentOperationOutcome};
use dbx_drivers::agent_runtime::{prepare_pl_debug_channel, PlDebugAgentChannel};
pub const PL_DEBUG_CONTINUE_TIMEOUT: Duration = Duration::from_secs(120);
pub const PL_DEBUG_RUN_TO_END_TIMEOUT: Duration = Duration::from_secs(300);
pub const PL_DEBUG_CLEANUP_TIMEOUT: Duration = Duration::from_secs(60);
pub const PL_DEBUG_LEASE: Duration = Duration::from_secs(120);
const QUICK_TIMEOUT: Duration = Duration::from_secs(30);
const MAX_SESSIONS: usize = 128;
const MAX_START_IDENTITIES: usize = 4096;
const MAX_OPERATIONS: usize = 4096;
const RESULT_TTL: Duration = Duration::from_secs(30 * 60);
const INACCESSIBLE: &str = "PL debug session is not accessible in this client context";
#[derive(Debug)]
pub enum PlDebugSubmissionError {
RejectedBeforeRegistration(String),
Unresolved(String),
}
impl PlDebugSubmissionError {
pub fn into_legacy_message(self) -> String {
match self {
Self::RejectedBeforeRegistration(message) | Self::Unresolved(message) => message,
}
}
pub fn into_backend_error(self) -> BackendError {
match self {
Self::RejectedBeforeRegistration(message) => BackendError::from_pl_debug_admission_rejection(&message),
Self::Unresolved(message) => BackendError::from_legacy_string(&message),
}
}
pub fn into_boundary_string(self) -> String {
match self {
Self::RejectedBeforeRegistration(_) => serde_json::to_string(&self.into_backend_error()).unwrap(),
Self::Unresolved(message) => message,
}
}
}
impl From<String> for PlDebugSubmissionError {
fn from(message: String) -> Self {
Self::Unresolved(message)
}
}
impl From<&str> for PlDebugSubmissionError {
fn from(message: &str) -> Self {
Self::Unresolved(message.into())
}
}
// Access identity is created at a trusted Rust request boundary, never from JSON.
#[derive(Clone, PartialEq, Eq, Hash)]
enum AccessOwner {
Desktop,
Web(String),
}
#[derive(Clone)]
pub struct PlDebugAccess {
owner: AccessOwner,
credential_owner: Option<String>,
}
pub enum PlDebugMutationScope {
Connections(Vec<String>),
WriteProtection { connection_id: String, credential_owner: Option<String> },
TunnelProfiles(Vec<String>),
Driver(String),
AllRuntimes,
}
pub struct PlDebugMutationPermit<'a> {
app: &'a AppState,
token: Uuid,
entries: Vec<(Arc<Entry>, u64)>,
inspections: Vec<Arc<InspectionOwner>>,
}
struct MutationIntent {
scope: PlDebugMutationScope,
connections: Vec<String>,
}
pub(crate) struct PlDebugPreparation {
entry: Arc<Entry>,
generation: u64,
}
impl PlDebugAccess {
pub fn desktop() -> Self {
Self { owner: AccessOwner::Desktop, credential_owner: current_credential_owner() }
}
/// The existing server-side cookie validation supplies `session`.
/// Password-disabled Web retains its original None credential scope.
pub fn web(session: String) -> Result<Self, String> {
if session.is_empty() {
return Err(INACCESSIBLE.into());
}
Ok(Self { owner: AccessOwner::Web(session), credential_owner: current_credential_owner() })
}
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlDebugStart {
pub server_epoch: Uuid,
pub operation_id: String,
pub connection_id: String,
pub database: String,
pub client_session_id: String,
pub target: Value,
pub risk_accepted: bool,
pub production_confirmed: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub expected_connection_revision: Option<String>,
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct PlDebugInspectTarget {
#[serde(default)]
pub schema: String,
pub object_type: String,
pub object_name: String,
#[serde(default)]
pub package_name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub metadata_preparation: Option<String>,
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct PlDebugInspect {
pub connection_id: String,
pub database: String,
pub client_session_id: String,
pub target: Option<PlDebugInspectTarget>,
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlDebugSessionRef {
pub server_epoch: Uuid,
pub session_id: String,
pub connection_id: String,
pub client_session_id: String,
}
#[derive(Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PlDebugAction {
Resume,
StepOver,
StepIn,
StepOut,
RunToEnd,
Abort,
Close,
Restart,
SetBreakpoints,
DeleteBreakpoints,
SetBreakpointEnabled,
SetExceptionBreakpoint,
SetValue,
Execute,
}
impl PlDebugAction {
fn method(self) -> &'static str {
match self {
Self::Resume => "pl_debug_resume",
Self::StepOver => "pl_debug_step_over",
Self::StepIn => "pl_debug_step_in",
Self::StepOut => "pl_debug_step_out",
Self::RunToEnd => "pl_debug_resume_ignore_breakpoints",
Self::Abort => "pl_debug_abort",
Self::Close => "pl_debug_close",
Self::Restart => "pl_debug_start",
Self::SetBreakpoints => "pl_debug_set_breakpoints",
Self::DeleteBreakpoints => "pl_debug_delete_breakpoints",
Self::SetBreakpointEnabled => "pl_debug_set_breakpoint_enabled",
Self::SetExceptionBreakpoint => "pl_debug_set_exception_breakpoint",
Self::SetValue => "pl_debug_set_value",
Self::Execute => "pl_debug_execute",
}
}
fn may_write(self) -> bool {
matches!(
self,
Self::Resume
| Self::StepOver
| Self::StepIn
| Self::StepOut
| Self::RunToEnd
| Self::Restart
| Self::SetValue
| Self::Execute
)
}
fn is_breakpoint(self) -> bool {
matches!(self, Self::SetBreakpoints | Self::DeleteBreakpoints | Self::SetBreakpointEnabled)
}
fn timeout(self) -> Duration {
match self {
Self::RunToEnd => PL_DEBUG_RUN_TO_END_TIMEOUT,
Self::Resume | Self::StepOver | Self::StepIn | Self::StepOut | Self::Abort => PL_DEBUG_CONTINUE_TIMEOUT,
_ => QUICK_TIMEOUT,
}
}
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlDebugOperation {
#[serde(flatten)]
pub session: PlDebugSessionRef,
pub operation_id: String,
pub expected_revision: u64,
pub generation: u64,
pub action: PlDebugAction,
#[serde(default = "empty_params")]
pub params: Value,
#[serde(default)]
pub production_confirmed: bool,
}
fn empty_params() -> Value {
json!({})
}
#[derive(Clone, Copy, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PlDebugReadKind {
Variables,
Value,
Stack,
Log,
LogPage,
Results,
ResultPage,
Breakpoints,
}
impl PlDebugReadKind {
fn method(self) -> &'static str {
match self {
Self::Variables => "pl_debug_get_variables",
Self::Value => "pl_debug_get_value",
Self::Stack => "pl_debug_get_stack",
Self::Log => "pl_debug_get_log",
Self::LogPage => "pl_debug_get_log_page",
Self::Results => "pl_debug_get_results",
Self::ResultPage => "pl_debug_get_result_page",
Self::Breakpoints => "pl_debug_list_breakpoints",
}
}
fn needs_stop(self) -> bool {
matches!(self, Self::Variables | Self::Value | Self::Stack)
}
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlDebugRead {
#[serde(flatten)]
pub session: PlDebugSessionRef,
pub generation: u64,
pub stop_revision: Option<u64>,
pub kind: PlDebugReadKind,
#[serde(default = "empty_params")]
pub params: Value,
}
#[derive(Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OperationState {
Accepted,
Running,
Succeeded,
Failed,
Unknown,
}
#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct PlDebugReceipt {
pub server_epoch: Uuid,
pub session_id: String,
pub operation_id: String,
pub generation: u64,
pub revision: u64,
pub state: OperationState,
pub dispatched: bool,
pub result: Option<Value>,
pub error: Option<Value>,
}
struct Operation {
request: Value,
receipt: PlDebugReceipt,
control_serial: u64,
action: Option<PlDebugAction>,
breakpoint_receipts: bool,
execute_receipts: bool,
effective_stop_revision: Option<u64>,
}
struct CloseIntent {
deadline: Instant,
done: bool,
reason: &'static str,
}
struct EntryState {
access_revoked: bool,
generation: u64,
revision: u64,
control_serial: u64,
agent_id: String,
scope: Uuid,
target: Value,
production_confirmed: bool,
lifecycle: ConnectionLifecycleSnapshot,
driver_key: Option<String>,
source_profile_ids: Option<Vec<String>>,
transport_plan: Option<ConnectionTransportPlan>,
transport_stamp: Option<ConnectionTransportStamp>,
channel: Option<PlDebugAgentChannel>,
start_finished: bool,
start_dispatched: bool,
active_operation: Option<String>,
interrupt_operation: Option<String>,
close_operation: Option<String>,
operations: HashMap<String, Operation>,
snapshot: Value,
retained_log: Option<Value>,
retained_results: results::RetainedResults,
last_heartbeat: Instant,
close: Option<CloseIntent>,
runtime_exited: bool,
retired_at: Option<Instant>,
}
impl EntryState {
fn protects_execution(&self) -> bool {
!self.runtime_exited
|| self.snapshot["releaseState"] != "released"
|| self.snapshot["executionOutcome"] == "unknown"
}
}
struct Entry {
id: String,
owner: AccessOwner,
credential_owner: Option<String>,
start: PlDebugStart,
app: Weak<AppState>,
state: Mutex<EntryState>,
changed: Notify,
}
impl Entry {
fn lock(&self) -> MutexGuard<'_, EntryState> {
self.state.lock().unwrap_or_else(|error| error.into_inner())
}
fn view(&self, epoch: Uuid) -> Value {
let data = self.lock();
let mut view = data.snapshot.clone();
let object = view.as_object_mut().expect("Core snapshots are objects");
object.insert("debugId".into(), json!(self.id));
object.insert("sessionId".into(), json!(self.id));
object.insert("serverEpoch".into(), json!(epoch));
object.insert("connectionId".into(), json!(self.start.connection_id));
object.insert("database".into(), json!(self.start.database));
object.insert("clientSessionId".into(), json!(self.start.client_session_id));
object.insert("startOperationId".into(), json!(self.start.operation_id));
object.insert("generation".into(), json!(data.generation));
object.insert("revision".into(), json!(data.revision));
object.insert("activeOperationId".into(), json!(data.active_operation));
let mut unresolved: Vec<_> = data
.operations
.iter()
.filter(|(_, operation)| {
operation.action.is_some()
&& matches!(
operation.receipt.state,
OperationState::Accepted | OperationState::Running | OperationState::Unknown
)
})
.collect();
unresolved.sort_by_key(|(_, operation)| operation.control_serial);
object.insert(
"recovery".into(),
json!({
"version": 1,
"closeOperationId": data.close_operation,
"operations": unresolved.into_iter().map(|(id, operation)| json!({
"operationId": id,
"action": operation.action,
"requestGeneration": operation.request["generation"],
"receiptGeneration": operation.receipt.generation,
"state": operation.receipt.state,
})).collect::<Vec<_>>(),
}),
);
object.insert("runtimeExited".into(), json!(data.runtime_exited));
object.insert("closing".into(), json!(data.close.as_ref().is_some_and(|close| !close.done)));
object.insert("target".into(), data.target.clone());
view
}
}
struct RegistryState {
sessions: HashMap<String, Arc<Entry>>,
inspections: HashMap<Uuid, Arc<InspectionOwner>>,
compilations: HashMap<(AccessOwner, String), Arc<compilation::Compilation>>,
// Expired identities remain tombstones for this process epoch.
starts: HashMap<(AccessOwner, String), Option<String>>,
accepting: bool,
connection_fences: HashMap<String, Uuid>,
retained_fences: std::collections::HashSet<Uuid>,
connection_gates: HashMap<String, Arc<tokio::sync::Mutex<()>>>,
connection_drains: HashMap<String, ConnectionDrainState>,
mutation_permits: HashMap<Uuid, MutationIntent>,
transports: HashMap<String, transport::TransportRecord>,
}
struct ConnectionDrain {
token: Uuid,
entries: Vec<Arc<Entry>>,
inspections: Vec<Arc<InspectionOwner>>,
deadline: Instant,
reason: &'static str,
}
struct ConnectionDrainState {
intent: Arc<ConnectionDrain>,
users: usize,
}
struct ConnectionDrainUse<'a> {
registry: &'a PlDebugRegistry,
connection_id: String,
intent: Arc<ConnectionDrain>,
completed: bool,
}
impl Drop for ConnectionDrainUse<'_> {
fn drop(&mut self) {
let mut registry = self.registry.lock();
let release = registry.connection_drains.get_mut(&self.connection_id).is_some_and(|current| {
if !Arc::ptr_eq(¤t.intent, &self.intent) {
return false;
}
current.users -= 1;
self.completed && current.users == 0
});
if release {
registry.connection_drains.remove(&self.connection_id);
if registry.connection_fences.get(&self.connection_id) == Some(&self.intent.token) {
registry.connection_fences.remove(&self.connection_id);
registry.retained_fences.remove(&self.intent.token);
}
}
drop(registry);
self.registry.changed.notify_waiters();
}
}
pub struct PlDebugRegistry {
epoch: Uuid,
state: Mutex<RegistryState>,
changed: Notify,
}
pub(crate) struct PlDebugConnectionFence<'a> {
registry: &'a PlDebugRegistry,
connection_id: String,
token: Uuid,
release: bool,
_mutation: Option<tokio::sync::OwnedMutexGuard<()>>,
drain: Option<ConnectionDrainUse<'a>>,
}
impl PlDebugConnectionFence<'_> {
pub(crate) fn complete(mut self) {
if let Some(drain) = &mut self.drain {
drain.completed = true;
}
self.release = true;
}
}
impl Drop for PlDebugConnectionFence<'_> {
fn drop(&mut self) {
if self.drain.is_some() || !self.release {
return;
}
let mut registry = self.registry.lock();
if registry.connection_fences.get(&self.connection_id) == Some(&self.token) {
registry.connection_fences.remove(&self.connection_id);
registry.retained_fences.remove(&self.token);
}
drop(registry);
self.registry.changed.notify_waiters();
}
}
impl Default for PlDebugRegistry {
fn default() -> Self {
Self {
epoch: Uuid::new_v4(),
state: Mutex::new(RegistryState {
sessions: HashMap::new(),
inspections: HashMap::new(),
compilations: HashMap::new(),
starts: HashMap::new(),
accepting: true,
connection_fences: HashMap::new(),
retained_fences: std::collections::HashSet::new(),
connection_gates: HashMap::new(),
connection_drains: HashMap::new(),
mutation_permits: HashMap::new(),
transports: HashMap::new(),
}),
changed: Notify::new(),
}
}
}
impl PlDebugRegistry {
fn lock(&self) -> MutexGuard<'_, RegistryState> {
self.state.lock().unwrap_or_else(|error| error.into_inner())
}
fn check_epoch(&self, epoch: Uuid) -> Result<(), String> {
if epoch != self.epoch {
return Err("unknown_after_restart: inspect the original execution before starting again".into());
}
Ok(())
}
pub(crate) fn try_idle_fence(&self, connection_id: &str) -> Option<PlDebugConnectionFence<'_>> {
let mut registry = self.lock();
if !registry.accepting
|| registry.connection_fences.contains_key(connection_id)
|| registry.connection_drains.contains_key(connection_id)
|| registry.mutation_permits.values().any(|scope| scope.blocks_start(connection_id))
|| registry.compilations.values().any(|entry| entry.protects_connection(connection_id))
|| registry
.inspections
.values()
.any(|owner| owner.request.connection_id == connection_id && !owner.resources_quiescent())
|| registry.sessions.values().any(|entry| {
if entry.start.connection_id != connection_id {
return false;
}
let data = entry.lock();
!data.runtime_exited
|| data.snapshot["releaseState"] != "released"
|| data.snapshot["executionOutcome"] == "unknown"
})
{
return None;
}
let token = Uuid::new_v4();
registry.connection_fences.insert(connection_id.to_owned(), token);
Some(PlDebugConnectionFence {
registry: self,
connection_id: connection_id.to_owned(),
token,
release: true,
_mutation: None,
drain: None,
})
}
fn find(&self, access: &PlDebugAccess, reference: &PlDebugSessionRef) -> Result<Arc<Entry>, String> {
self.check_epoch(reference.server_epoch)?;
self.lock()
.sessions
.get(&reference.session_id)
.filter(|entry| {
entry.owner == access.owner
&& entry.start.connection_id == reference.connection_id
&& entry.start.client_session_id == reference.client_session_id
&& !entry.lock().access_revoked
})
.cloned()
.ok_or_else(|| INACCESSIBLE.into())
}
fn register(
&self,
app: &Arc<AppState>,
access: &PlDebugAccess,
start: PlDebugStart,
) -> Result<(Arc<Entry>, bool), PlDebugSubmissionError> {
self.check_epoch(start.server_epoch)?;
validate_identity(&start.operation_id)?;
validate_identity(&start.client_session_id)?;
let key = (access.owner.clone(), start.operation_id.clone());
let mut registry = self.lock();
if let Some(previous) = registry.starts.get(&key) {
let entry = previous
.as_ref()
.and_then(|id| registry.sessions.get(id))
.ok_or("PL debug result expired; this start identity cannot execute again")?;
if entry.lock().access_revoked {
return Err(INACCESSIBLE.into());
}
if serde_json::to_value(&entry.start).unwrap() != serde_json::to_value(&start).unwrap() {
return Err("The start operation identity already belongs to a different request".into());
}
return Ok((entry.clone(), false));
}
let rejected = |message: &str| PlDebugSubmissionError::RejectedBeforeRegistration(message.into());
if !start.target.is_object() {
return Err(rejected("Debug target must be an object"));
}
let expired = registry
.sessions
.values()
.filter(|entry| {
let data = entry.lock();
data.retired_at.is_some_and(|time| time.elapsed() >= RESULT_TTL)
&& data.snapshot["releaseState"] == "released"
&& data.snapshot["executionOutcome"] != "unknown"
})
.map(|entry| entry.id.clone())
.collect::<Vec<_>>();
for id in expired {
if let Some(entry) = registry.sessions.remove(&id) {
registry.starts.insert((entry.owner.clone(), entry.start.operation_id.clone()), None);
}
}
if !registry.accepting {
return Err(rejected("The application is shutting down"));
}
if registry.connection_fences.contains_key(&start.connection_id)
|| registry.connection_drains.contains_key(&start.connection_id)
|| registry.mutation_permits.values().any(|scope| scope.blocks_start(&start.connection_id))
|| registry.inspections.values().any(|owner| owner.blocks_debug_start(&start.connection_id))
|| registry.compilations.values().any(|entry| entry.protects_connection(&start.connection_id))
{
return Err(rejected("The connection is being cleaned up; wait before starting a new debug session"));
}
if registry.sessions.values().any(|entry| {
if entry.owner != access.owner
|| entry.start.connection_id != start.connection_id
|| entry.start.client_session_id != start.client_session_id
{
return false;
}
let data = entry.lock();
!data.runtime_exited
|| data.snapshot["releaseState"] != "released"
|| data.snapshot["executionOutcome"] == "unknown"
}) {
return Err(rejected(
"This client already has an unresolved debug session; restore or close it before starting again",
));
}
if registry.sessions.len() >= MAX_SESSIONS || registry.starts.len() >= MAX_START_IDENTITIES {
return Err(rejected(
"PL debug session/receipt capacity reached; retained unknown executions cannot be evicted",
));
}
let lifecycle = app.connection_lifecycle_snapshot(&start.connection_id);
if start
.expected_connection_revision
.as_ref()
.is_some_and(|revision| revision != &connection_revision(self.epoch, &lifecycle))
{
return Err(rejected("The connection changed after the debug preview; inspect the target again"));
}
let id = Uuid::new_v4().to_string();
let receipt = PlDebugReceipt {
server_epoch: self.epoch,
session_id: id.clone(),
operation_id: start.operation_id.clone(),
generation: 1,
revision: 1,
state: OperationState::Accepted,
dispatched: false,
result: None,
error: None,
};
let operation = Operation {
request: serde_json::to_value(&start).unwrap(),
receipt,
control_serial: 1,
action: None,
breakpoint_receipts: false,
execute_receipts: false,
effective_stop_revision: None,
};
let entry = Arc::new(Entry {
id: id.clone(),
owner: access.owner.clone(),
credential_owner: access.credential_owner.clone(),
app: Arc::downgrade(app),
state: Mutex::new(EntryState {
access_revoked: false,
generation: 1,
revision: 1,
control_serial: 1,
agent_id: Uuid::new_v4().simple().to_string(),
scope: Uuid::new_v4(),
target: start.target.clone(),
production_confirmed: start.production_confirmed,
lifecycle,
driver_key: None,
source_profile_ids: None,
transport_plan: None,
transport_stamp: None,
channel: None,
start_finished: false,
start_dispatched: false,
active_operation: Some(start.operation_id.clone()),
interrupt_operation: None,
close_operation: None,
operations: HashMap::from([(start.operation_id.clone(), operation)]),
snapshot: initial_snapshot(),
retained_log: None,
retained_results: results::RetainedResults::default(),
last_heartbeat: Instant::now(),
close: None,
runtime_exited: false,
retired_at: None,
}),
start,
changed: Notify::new(),
});
registry.starts.insert(key, Some(id.clone()));
registry.sessions.insert(id, entry.clone());
Ok((entry, true))
}
}
fn initial_snapshot() -> Value {
json!({"state":"starting","executionOutcome":"pending","releaseState":"open",
"transactionOutcome":"pending","targetDispatched":false,"executionStopped":false})
}
fn validate_identity(id: &str) -> Result<(), String> {
if id.is_empty() || id.len() > 128 || !id.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'_' || c == b'-') {
return Err("A stable client/operation identity of 1–128 ASCII letters, digits, '_' or '-' is required".into());
}
Ok(())
}
pub fn pl_debug_bootstrap_core(state: &AppState) -> Value {
json!({"serverEpoch":state.pl_debug.epoch,"heartbeatSeconds":15,"leaseSeconds":PL_DEBUG_LEASE.as_secs(),
"cleanupSeconds":PL_DEBUG_CLEANUP_TIMEOUT.as_secs()})
}
fn connection_revision(epoch: Uuid, lifecycle: &ConnectionLifecycleSnapshot) -> String {
format!("{epoch}:{}", lifecycle.generation())
}
pub async fn pl_debug_inspect_core(
state: &AppState,
access: &PlDebugAccess,
request: PlDebugInspect,
) -> Result<Value, String> {
validate_identity(&request.client_session_id)?;
let db_type = state
.configs
.read()
.await
.get(&request.connection_id)
.map(|config| config.db_type)
.ok_or("Connection not found")?;
if !matches!(
db_type,
crate::models::connection::DatabaseType::Oracle | crate::models::connection::DatabaseType::OceanbaseOracle
) {
return Err("PL/SQL debugging requires an Oracle or OceanBase Oracle connection".into());
}
let preparation = request.target.as_ref().and_then(|target| target.metadata_preparation.as_deref());
if preparation == Some("debug_compile") {
return Err("Debug compilation inspection requires its registered dedicated channel".into());
}
if preparation.is_some_and(|policy| policy != "type_only") {
return Err("Unsupported type metadata preparation policy".into());
}
let prepare_types = preparation.is_some();
if prepare_types && db_type != crate::models::connection::DatabaseType::OceanbaseOracle {
return Err("Oracle typed metadata inspection requires its registered dedicated channel".into());
}
with_credential_owner(access.credential_owner.clone(), async {
let lifecycle = state.connection_lifecycle_snapshot(&request.connection_id);
let inspect_once = || async {
if !state.connection_lifecycle_is_current(&request.connection_id, &lifecycle) {
return Err("The debug inspection expired; inspect the target again".into());
}
let pool_key = state
.get_or_create_metadata_pool_for_session(
&request.connection_id,
Some(&request.database),
Some(&request.client_session_id),
)
.await?;
let Some(crate::connection::PoolKind::Agent(client)) = state.pool_handle(&pool_key).await else {
return Err("PL/SQL debug inspection requires the connection's metadata Agent".into());
};
let result = client
.lock()
.await
.call_method_with_timeout::<Value>(
crate::db::agent_driver::AgentMethod::PlDebugInspect,
json!({"target": request.target}),
Some(if prepare_types { QUICK_TIMEOUT + QUICK_TIMEOUT } else { QUICK_TIMEOUT }),
)
.await?;
let same_pool = matches!(state.pool_handle(&pool_key).await,
Some(crate::connection::PoolKind::Agent(current)) if Arc::ptr_eq(&client, ¤t));
if !same_pool || !state.connection_lifecycle_is_current(&request.connection_id, &lifecycle) {
return Err("The debug inspection expired; inspect the target again".into());
}
let mut result = result;
let object = result.as_object_mut().ok_or("Invalid debug inspection response")?;
object.insert("connectionRevision".into(), json!(connection_revision(state.pl_debug.epoch, &lifecycle)));
Ok(result)
};
Box::pin(crate::schema::run_metadata_connection_for_session(
state,
&request.connection_id,
Some(&request.database),
Some(&request.client_session_id),
!prepare_types,
inspect_once,
))
.await
})
.await
}
pub fn pl_debug_revoke_web_owner_core(state: &AppState, token: &str) {
let owner = AccessOwner::Web(token.to_owned());
compilation::revoke(&state.pl_debug.lock(), &owner);
let entries =
state.pl_debug.lock().sessions.values().filter(|entry| entry.owner == owner).cloned().collect::<Vec<_>>();
let deadline = Instant::now() + PL_DEBUG_CLEANUP_TIMEOUT;
for entry in entries {
entry.lock().access_revoked = true;
request_close(&entry, "owner_revoked", deadline);
}
let inspections = state
.pl_debug
.lock()
.inspections
.values()
.filter(|inspection| inspection.belongs_to(&owner))
.cloned()
.collect::<Vec<_>>();
for inspection in inspections {
inspection.invalidate();
}
}
pub fn pl_debug_list_core(
state: &AppState,
access: &PlDebugAccess,
epoch: Uuid,
connection_id: &str,
) -> Result<Vec<Value>, String> {
state.pl_debug.check_epoch(epoch)?;
let entries = state
.pl_debug
.lock()
.sessions
.values()
.filter(|entry| {
entry.owner == access.owner && entry.start.connection_id == connection_id && !entry.lock().access_revoked
})
.cloned()
.collect::<Vec<_>>();
Ok(entries.iter().map(|entry| entry.view(epoch)).collect())
}
pub async fn pl_debug_heartbeat_core(
state: &AppState,
access: &PlDebugAccess,
reference: &PlDebugSessionRef,
) -> Result<Value, String> {
let entry = state.pl_debug.find(access, reference)?;
let pending = {
let mut data = entry.lock();
if data.close.is_none() && !data.runtime_exited {
data.last_heartbeat = Instant::now();
if data.start_dispatched {
data.channel.clone().map(|channel| (channel, data.agent_id.clone(), data.generation, data.revision))
} else {
None
}
} else {
None
}
};
entry.changed.notify_waiters();
if let Some((channel, agent_id, generation, revision)) = pending {
let value = channel
.call::<Value>("pl_debug_heartbeat", json!({"debugId":agent_id}), QUICK_TIMEOUT, None)
.await
.map_err(|error| error.into_legacy_string())?;
let mut data = entry.lock();
if data.generation == generation && data.revision == revision && data.close.is_none() {
apply_agent_snapshot(&mut data, &value);
data.revision += 1;
}
}
Ok(entry.view(state.pl_debug.epoch))
}
pub fn pl_debug_operation_core(
state: &AppState,
access: &PlDebugAccess,
reference: &PlDebugSessionRef,
operation_id: &str,
) -> Result<PlDebugReceipt, String> {
let entry = state.pl_debug.find(access, reference)?;
let receipt = entry
.lock()
.operations
.get(operation_id)
.map(|operation| operation.receipt.clone())
.ok_or("PL debug operation is not available in this session")?;
Ok(receipt)
}
pub fn pl_debug_start_core(
state: &Arc<AppState>,
access: &PlDebugAccess,
start: PlDebugStart,
) -> Result<PlDebugReceipt, String> {
pl_debug_start_submission_core(state, access, start).map_err(PlDebugSubmissionError::into_legacy_message)
}
pub fn pl_debug_start_submission_core(
state: &Arc<AppState>,
access: &PlDebugAccess,
start: PlDebugStart,
) -> Result<PlDebugReceipt, PlDebugSubmissionError> {
let id = start.operation_id.clone();
let (entry, fresh) = state.pl_debug.register(state, access, start)?;
if fresh {
spawn_start(state, entry.clone(), id.clone(), 1);
spawn_watchdog(state, entry.clone());
}
let receipt = entry.lock().operations[&id].receipt.clone();
Ok(receipt)
}
async fn check_write_protection(state: &AppState, entry: &Entry, production_confirmed: bool) -> Result<(), String> {
if let Some(name) = super::connection_readonly_name(state, &entry.start.connection_id).await {
return Err(format!("Connection '{name}' is read-only; unlock writes before running or changing the debuggee"));
}
let configs = state.configs.read().await;
let config = configs.get(&entry.start.connection_id).ok_or("The original connection no longer exists")?;
if crate::production_safety::is_production_database(config, &entry.start.database) && !production_confirmed {
return Err("Production execution requires confirmation bound to this debug request".into());
}
Ok(())
}
fn local_failure(code: &str, message: impl Into<String>, dispatched: bool) -> Value {
json!({"code":code,"message":message.into(),"operationOutcome":if dispatched {"unknown"} else {"not_started"}})
}
fn call_failure(error: AgentCallError) -> Value {
let outcome =
if error.operation_outcome() == AgentOperationOutcome::NotStarted { "not_started" } else { "unknown" };
json!({"code":"agent_call_failed","operationOutcome":outcome,"detail":crate::backend_error::BackendError::from_agent_call_error(&error)})
}
fn apply_agent_snapshot(data: &mut EntryState, value: &Value) {
let snapshot = value.get("snapshot").unwrap_or(value);
if snapshot.is_object() && snapshot.get("state").is_some() {
data.snapshot = snapshot.clone();
}
}
fn assignment_result_state(value: &Value) -> Option<OperationState> {
match (value["ok"].as_bool(), value["result"].as_i64()) {
(Some(true), Some(0)) => Some(OperationState::Succeeded),
(Some(false), Some(code)) if code != 0 => Some(OperationState::Failed),
_ => None,
}
}
fn execute_result_state(value: &Value, id: &str, stop: Option<u64>, native: bool) -> Option<OperationState> {
let ok = value["ok"].as_bool()?;
let rows = value["rows"].as_array()?;
if !rows.iter().all(|row| row.is_null() || row.is_string()) || value["count"].as_u64()? != rows.len() as u64 {
return None;
}
if native {
if stop.is_none()
|| value["operationId"] != id
|| value["action"] != "execute"
|| value["stopRevision"].as_u64() != stop
{
return None;
}
let complete = value["complete"].as_bool()?;
let truncated = value["truncated"].as_bool()?;
if (complete && truncated)
|| (!complete && !truncated && !value["resultError"].as_str().is_some_and(|message| !message.is_empty()))
{
return None;
}
}
if ok {
if value["error"].as_str().is_some_and(|message| !message.is_empty()) {
return None;
}
Some(OperationState::Succeeded)
} else if value["error"].as_str().or_else(|| value["message"].as_str()).is_some_and(|message| !message.is_empty()) {
Some(OperationState::Failed)
} else {
None
}
}
fn finish_operation(entry: &Entry, id: &str, generation: u64, result: Result<Value, Value>) {
let mut data = entry.lock();
let Some(operation) = data.operations.get(id) else {
return;
};
let current = data.generation == generation && data.control_serial == operation.control_serial;
let (status, result_value, error_value) = match result {
Ok(value) if operation.breakpoint_receipts => {
match (value["operationId"] == id && value["stopRevision"].as_u64() == operation.effective_stop_revision)
.then(|| assignment_result_state(&value))
.flatten()
{
Some(state) => (state, Some(value), None),
None => (
OperationState::Unknown,
None,
Some(local_failure(
"invalid_breakpoint_result",
"The original breakpoint operation returned an invalid command result",
true,
)),
),
}
}
Ok(value) if operation.action == Some(PlDebugAction::SetValue) => match assignment_result_state(&value) {
Some(state) => (state, Some(value), None),
None => (
OperationState::Unknown,
None,
Some(local_failure(
"invalid_assignment_result",
"The original assignment returned an invalid command result",
true,
)),
),
},
Ok(value) if operation.action == Some(PlDebugAction::Execute) => {
match execute_result_state(&value, id, operation.effective_stop_revision, operation.execute_receipts) {
Some(state) => (state, Some(value), None),
None => (
OperationState::Unknown,
None,
Some(local_failure(
"invalid_execute_result",
"The original SQL operation returned an invalid result; do not repeat it",
true,
)),
),
}
}
Ok(value) => (OperationState::Succeeded, Some(value), None),
Err(error) => (
if error["operationOutcome"] == "not_started" { OperationState::Failed } else { OperationState::Unknown },
None,
Some(error),
),
};
if current {
if let Some(value) = &result_value {
apply_agent_snapshot(&mut data, value);
} else if status == OperationState::Unknown {
data.snapshot["state"] = json!("unknown");
data.snapshot["observationError"] = error_value.clone().unwrap();
}
data.revision += 1;
}
if data.active_operation.as_deref() == Some(id) {
data.active_operation = None;
}
if data.interrupt_operation.as_deref() == Some(id) {
data.interrupt_operation = None;
}
let revision = data.revision;
if let Some(operation) = data.operations.get_mut(id) {
operation.receipt.state = status;
operation.receipt.result = result_value;
operation.receipt.error = error_value;
operation.receipt.revision = revision;
}
drop(data);
entry.changed.notify_waiters();
}
fn spawn_start(state: &Arc<AppState>, entry: Arc<Entry>, id: String, generation: u64) {
let weak = Arc::downgrade(state);
let task_entry = entry.clone();
let task_id = id.clone();
let accepted = state.pl_debug_supervisor().spawn_once(
format!("pl-debug-start:{}:{generation}", entry.id),
move |_| async move {
let result = match weak.upgrade() {
Some(state) => {
with_credential_owner(
task_entry.credential_owner.clone(),
run_start(&state, &task_entry, &task_id, generation),
)
.await
}
None => Err(local_failure("application_closed", "Application state is no longer available", false)),
};
{
let mut data = task_entry.lock();
if data.generation == generation {
data.start_finished = true;
}
}
let failed = result.is_err();
finish_operation(&task_entry, &task_id, generation, result);
if failed {
request_close(&task_entry, "start_failed", Instant::now() + PL_DEBUG_CLEANUP_TIMEOUT);
}
},
);
if !accepted {
entry.lock().start_finished = true;
finish_operation(
&entry,
&id,
generation,
Err(local_failure("application_closed", "The application is shutting down", false)),
);
request_close(&entry, "application_shutdown", Instant::now());
}
}
async fn run_start(state: &AppState, entry: &Arc<Entry>, id: &str, generation: u64) -> Result<Value, Value> {
if !entry.start.risk_accepted {
return Err(local_failure(
"confirmation_required",
"Confirm possible target writes, commits and controller-loss risk before debugging",
false,
));
}
let (lifecycle, scope, agent_id, mut target, confirmed) = {
let mut data = entry.lock();
if data.generation != generation || data.close.is_some() || data.access_revoked {
return Err(local_failure("start_cancelled", "Debug start was stopped before dispatch", false));
}
data.operations.get_mut(id).unwrap().receipt.state = OperationState::Running;
(data.lifecycle.clone(), data.scope, data.agent_id.clone(), data.target.clone(), data.production_confirmed)
};
check_write_protection(state, entry, confirmed)
.await
.map_err(|error| local_failure("write_protected", error, false))?;
let prepared = state
.prepare_pl_debug_connection(
&entry.start.connection_id,
Some(&entry.start.database),
&lifecycle,
&PlDebugPreparation { entry: entry.clone(), generation },
)
.await
.map_err(|error| local_failure("connection_preparation_failed", error, false))?;
let channel = prepare_pl_debug_channel(
&state.agent_manager,
&prepared.config.db_type,
prepared.config.driver_profile.as_deref(),
&prepared.config.agent_java_options,
prepared.transport_stamp.agent_launch_env(),
Uuid::new_v4().simple().to_string(),
scope,
)
.await
.map_err(|error| local_failure("agent_preparation_failed", error, false))?;
{
let mut data = entry.lock();
data.channel = Some(channel.clone());
if data.close.is_some() || data.generation != generation || data.access_revoked {
if data.close.as_ref().is_some_and(|close| close.deadline <= Instant::now()) {
channel.fail_stop();
}
drop(data);
entry.changed.notify_waiters();
return Err(local_failure(
"start_cancelled",
"Debug start was stopped before opening its original session",
false,
));
}
}
entry.changed.notify_waiters();
if !channel.supports_native_pl_debug() {
return Err(local_failure(
"native_agent_required",
"This Agent does not advertise the native no-helper PL debug contract; update the Agent before debugging",
false,
));
}
let params = agent_connect_params_with_role(
&prepared.config,
&prepared.endpoint.host,
prepared.endpoint.port,
prepared.config.effective_database().unwrap_or(""),
AgentSessionRole::Metadata,
)
.map_err(|error| local_failure("invalid_connection", error, false))?;
PlDebugPreparation { entry: entry.clone(), generation }
.validate_transport(state)
.map_err(|error| local_failure("connection_changed", error, false))?;
channel.open_session(params, agent_connect_timeout(&prepared.config)).await.map_err(call_failure)?;
check_write_protection(state, entry, confirmed)
.await
.map_err(|error| local_failure("write_protected", error, false))?;
PlDebugPreparation { entry: entry.clone(), generation }
.validate_transport(state)
.map_err(|error| local_failure("connection_changed", error, false))?;
{
let mut data = entry.lock();
if data.close.is_some()
|| data.access_revoked
|| data.generation != generation
|| !state.connection_lifecycle_is_current(&entry.start.connection_id, &lifecycle)
{
return Err(local_failure(
"start_cancelled",
"The original debug connection changed before target dispatch",
false,
));
}
data.start_dispatched = true;
data.operations.get_mut(id).unwrap().receipt.dispatched = true;
}
target.as_object_mut().unwrap().insert("operationId".into(), json!(agent_id));
channel.call("pl_debug_start", target, PL_DEBUG_CONTINUE_TIMEOUT, None).await.map_err(call_failure)
}
pub async fn pl_debug_status_core(
state: &AppState,
access: &PlDebugAccess,
reference: &PlDebugSessionRef,
refresh: bool,
) -> Result<Value, String> {
let entry = state.pl_debug.find(access, reference)?;
if refresh {
let (channel, agent_id, generation, revision, dispatched) = {
let data = entry.lock();
(data.channel.clone(), data.agent_id.clone(), data.generation, data.revision, data.start_dispatched)
};
if let Some(channel) = channel {
if channel.wait_for_exit(Duration::ZERO).await {
confirm_exit(&entry, &channel).await;
} else if dispatched {
let result =
channel.call::<Value>("pl_debug_status", json!({"debugId":agent_id}), QUICK_TIMEOUT, None).await;
{
let mut data = entry.lock();
if data.generation == generation && data.revision == revision {
match result {
Ok(value) => {
apply_agent_snapshot(&mut data, &value);
if data.operations.values().any(|operation| {
(matches!(operation.action, Some(PlDebugAction::SetValue | PlDebugAction::Execute))
|| operation.breakpoint_receipts)
&& operation.receipt.state == OperationState::Unknown
&& operation.receipt.generation == generation
&& operation.control_serial == data.control_serial
}) {
data.snapshot["state"] = json!("unknown");
}
data.revision += 1;
}
Err(error) => {
data.snapshot["observationError"] = call_failure(error);
}
}
}
}
if channel.supports_set_value_operation_status()
|| channel.supports_breakpoint_operation_status()
|| channel.supports_execute_operation_status()
{
recover_value_operations(&entry, &channel, &agent_id, generation).await;
}
}
}
}
Ok(entry.view(state.pl_debug.epoch))
}
async fn recover_value_operations(entry: &Entry, channel: &PlDebugAgentChannel, agent_id: &str, generation: u64) {
let operations = {
let data = entry.lock();
if data.generation != generation || data.runtime_exited {
return;
}
data.operations
.iter()
.filter(|(_, operation)| {
((operation.action == Some(PlDebugAction::SetValue) && channel.supports_set_value_operation_status())
|| (operation.execute_receipts && channel.supports_execute_operation_status())
|| (operation.breakpoint_receipts && channel.supports_breakpoint_operation_status()))
&& operation.receipt.state == OperationState::Unknown
&& operation.receipt.dispatched
&& operation.receipt.generation == generation
})
.map(|(id, operation)| {
(
id.clone(),
operation.control_serial,
json!(operation.effective_stop_revision),
operation.action.unwrap().method().trim_start_matches("pl_debug_"),
)
})
.collect::<Vec<_>>()
};
for (id, serial, stop_revision, action) in operations {
let Ok(record) = channel
.call::<Value>(
"pl_debug_operation_status",
json!({"debugId":agent_id,"operationId":id}),
QUICK_TIMEOUT,
None,
)
.await
else {
continue;
};
let value = &record["result"];
let rejection = &record["error"];
let not_started = record["state"] == "failed"
&& rejection["contractVersion"] == 1
&& ((rejection["category"] == "protocol" && rejection["stage"] == "request")
|| (action == "execute"
&& rejection["category"] == "sql"
&& rejection["stage"] == "prepare"
&& value.is_null()))
&& rejection["retryable"] == false
&& rejection["sessionDisposition"] == "keep"
&& rejection["operationOutcome"] == "not_started"
&& (value.is_null()
|| (value["ok"] == false
&& value.get("result").is_none()
&& value["operationId"] == id
&& value["stopRevision"] == stop_revision
&& value["items"].as_array().is_some_and(|items| {
!items.is_empty()
&& items.iter().all(|item| item["state"] == "failed" || item["state"] == "not_started")
})
&& value["breakpoints"].as_array().is_some_and(Vec::is_empty)));
let status = if not_started {
OperationState::Failed
} else if let Some(status) = if action == "execute" {
execute_result_state(value, &id, stop_revision.as_u64(), true)
} else {
assignment_result_state(value)
} {
if !rejection.is_null() {
continue;
}
status
} else {
continue;
};
let expected_state = if status == OperationState::Succeeded { "succeeded" } else { "failed" };
if record["operationId"] != id
|| record["action"] != action
|| record["state"] != expected_state
|| record["stopRevision"] != stop_revision
|| (!not_started && (value["operationId"] != id || value["stopRevision"] != stop_revision))
{
continue;
}
let mut data = entry.lock();
if data.generation != generation || data.agent_id != agent_id || data.runtime_exited {
continue;
}
let Some(operation) = data.operations.get(&id) else {
continue;
};
if operation.receipt.state != OperationState::Unknown || operation.control_serial != serial {
continue;
}
if !not_started
&& data.control_serial == serial
&& data.close.is_none()
&& !data.access_revoked
&& data.active_operation.is_none()
&& data.interrupt_operation.is_none()
&& data.snapshot["executionStopped"] != true
&& data.snapshot["targetReturned"] != true
&& data.snapshot["stopRevision"] == stop_revision
{
apply_agent_snapshot(&mut data, value);
}
data.revision += 1;
let revision = data.revision;
let operation = data.operations.get_mut(&id).unwrap();
operation.receipt.state = status;
operation.receipt.result = (!value.is_null()).then(|| value.clone());
operation.receipt.error = not_started.then(|| rejection.clone());
operation.receipt.revision = revision;
drop(data);
entry.changed.notify_waiters();
}
}
pub async fn pl_debug_operate_core(
state: &Arc<AppState>,
access: &PlDebugAccess,
request: PlDebugOperation,
) -> Result<PlDebugReceipt, String> {
pl_debug_operate_submission_core(state, access, request).await.map_err(PlDebugSubmissionError::into_legacy_message)
}
fn legacy_breakpoint_request(request: &PlDebugOperation) -> bool {
let params = &request.params;
if ["registrationId", "sourceRefId", "sourceRevision", "nativeFrameId", "line", "rules"]
.iter()
.any(|key| params.get(key).is_some())
{
return false;
}
match request.action {
PlDebugAction::SetBreakpoints | PlDebugAction::DeleteBreakpoints => params["breakpoints"].is_array(),
PlDebugAction::SetBreakpointEnabled => {
params.get("breakpoints").is_none()
&& params["breakpointNumber"].as_u64().is_some_and(|number| number > 0 && number <= i32::MAX as u64)
&& params["enabled"].is_boolean()
}
_ => false,
}
}
pub async fn pl_debug_operate_submission_core(
state: &Arc<AppState>,
access: &PlDebugAccess,
request: PlDebugOperation,
) -> Result<PlDebugReceipt, PlDebugSubmissionError> {
let entry = state.pl_debug.find(access, &request.session)?;
validate_identity(&request.operation_id)?;
let frozen = serde_json::to_value(&request).unwrap();
{
let data = entry.lock();
if let Some(operation) = data.operations.get(&request.operation_id) {
if operation.request != frozen {
return Err("The operation identity already belongs to a different request".into());
}
return Ok(operation.receipt.clone());
}
}
let validation = if !request.params.is_object() {
Err("Debug operation parameters must be an object".into())
} else if request.action == PlDebugAction::Restart
&& request.params.get("target").is_some_and(|target| !target.is_object())
{
Err("Debug target must be an object".into())
} else if request.action.may_write() {
with_credential_owner(
entry.credential_owner.clone(),
check_write_protection(state, &entry, request.production_confirmed),
)
.await
} else {
Ok(())
};
let admission = (request.action == PlDebugAction::Restart).then(|| state.pl_debug.lock());
{
let mut data = entry.lock();
if data.access_revoked {
return Err(INACCESSIBLE.into());
}
if let Some(operation) = data.operations.get(&request.operation_id) {
if operation.request != frozen {
return Err("The operation identity already belongs to a different request".into());
}
return Ok(operation.receipt.clone());
}
let rejected = |message: &str| PlDebugSubmissionError::RejectedBeforeRegistration(message.into());
let breakpoint_receipts = request.action.is_breakpoint()
&& data.channel.as_ref().is_some_and(|channel| channel.supports_breakpoint_operation_status());
let execute_receipts = request.action == PlDebugAction::Execute
&& data.channel.as_ref().is_some_and(|channel| channel.supports_execute_operation_status());
validation.map_err(PlDebugSubmissionError::RejectedBeforeRegistration)?;
if data.generation != request.generation || data.revision != request.expected_revision {
return Err(rejected("The debug state changed; refresh before submitting a new operation"));
}
if request.action == PlDebugAction::Close {
if let Some(id) = &data.close_operation {
return Ok(data.operations[id].receipt.clone());
}
} else if data.close.is_some() && request.action != PlDebugAction::Restart {
return Err(rejected("The original debug session is closing or isolated; inspect its retained status"));
}
let reserved = matches!(request.action, PlDebugAction::Abort | PlDebugAction::Close);
if data.operations.len() >= if reserved { MAX_OPERATIONS } else { MAX_OPERATIONS - 2 } {
return Err(rejected("PL debug operation receipt capacity reached; original intents are retained"));
}
if request.action == PlDebugAction::Restart {
let registry = admission.as_ref().unwrap();
if !registry.accepting
|| registry.connection_fences.contains_key(&entry.start.connection_id)
|| registry.connection_drains.contains_key(&entry.start.connection_id)
|| registry.mutation_permits.values().any(|scope| scope.blocks_start(&entry.start.connection_id))
|| registry.inspections.values().any(|owner| owner.blocks_debug_start(&entry.start.connection_id))
|| registry
.compilations
.values()
.any(|compilation| compilation.protects_connection(&entry.start.connection_id))
{
return Err(rejected("The connection is being cleaned up; wait before starting a new debug session"));
}
if !data.runtime_exited
|| data.active_operation.is_some()
|| data.close.as_ref().is_some_and(|close| !close.done)
|| data.snapshot["executionStopped"] != true
|| data.snapshot["releaseState"] != "released"
|| data.snapshot["executionOutcome"] == "unknown"
{
return Err(rejected(
"Confirm the previous program stopped and its original resources were released before restarting",
));
}
data.generation += 1;
data.agent_id = Uuid::new_v4().simple().to_string();
data.scope = Uuid::new_v4();
data.channel = None;
data.driver_key = None;
data.source_profile_ids = None;
data.transport_plan = None;
data.transport_stamp = None;
data.start_finished = false;
data.start_dispatched = false;
data.last_heartbeat = Instant::now();
data.close = None;
data.close_operation = None;
data.retained_log = None;
data.runtime_exited = false;
data.retired_at = None;
data.production_confirmed = request.production_confirmed;
data.lifecycle = state.connection_lifecycle_snapshot(&entry.start.connection_id);
if let Some(target) = request.params.get("target") {
data.target = target.clone();
}
data.snapshot = initial_snapshot();
} else if request.action == PlDebugAction::Abort {
if data.interrupt_operation.is_some() {
return Err(rejected("A debug abort is already running"));
}
} else if request.action != PlDebugAction::Close {
if data.active_operation.is_some() {
return Err(rejected("A debug operation is already running"));
}
if data.snapshot["state"] != "paused" {
return Err(rejected("This operation requires a current paused debug stop"));
}
let legacy_revision = (request.action == PlDebugAction::Execute
|| (breakpoint_receipts && legacy_breakpoint_request(&request)))
&& request.params.get("stopRevision").is_none();
if (request.action == PlDebugAction::SetValue
|| breakpoint_receipts
|| request.action == PlDebugAction::Execute)
&& ((!legacy_revision && request.params.get("stopRevision").and_then(Value::as_u64).is_none())
|| (legacy_revision && data.snapshot["stopRevision"].as_u64().is_none())
|| (!legacy_revision && request.params.get("stopRevision") != data.snapshot.get("stopRevision")))
{
return Err(rejected(
"The requested operation belongs to an old debug stop; read it again before changing it",
));
}
}
data.control_serial += 1;
data.revision += 1;
let receipt = PlDebugReceipt {
server_epoch: state.pl_debug.epoch,
session_id: entry.id.clone(),
operation_id: request.operation_id.clone(),
generation: data.generation,
revision: data.revision,
state: OperationState::Accepted,
dispatched: false,
result: None,
error: None,
};
let control_serial = data.control_serial;
let effective_stop_revision = if (breakpoint_receipts || request.action == PlDebugAction::Execute)
&& request.params.get("stopRevision").is_none()
{
data.snapshot["stopRevision"].as_u64()
} else {
request.params["stopRevision"].as_u64()
};
data.operations.insert(
request.operation_id.clone(),
Operation {
request: frozen,
receipt,
control_serial,
action: Some(request.action),
breakpoint_receipts,
execute_receipts,
effective_stop_revision,
},
);
match request.action {
PlDebugAction::Abort => data.interrupt_operation = Some(request.operation_id.clone()),
PlDebugAction::Close => data.close_operation = Some(request.operation_id.clone()),
_ => data.active_operation = Some(request.operation_id.clone()),
}
}
drop(admission);
let generation = entry.lock().generation;
match request.action {
PlDebugAction::Close => request_close(&entry, "client_close", Instant::now() + PL_DEBUG_CLEANUP_TIMEOUT),
PlDebugAction::Restart => {
spawn_start(state, entry.clone(), request.operation_id.clone(), generation);
spawn_watchdog(state, entry.clone());
}
_ => spawn_control(state, entry.clone(), request.clone(), generation),
}
let receipt = entry.lock().operations[&request.operation_id].receipt.clone();
Ok(receipt)
}
fn spawn_control(state: &Arc<AppState>, entry: Arc<Entry>, request: PlDebugOperation, generation: u64) {
let task_entry = entry.clone();
let id = request.operation_id.clone();
if !state.pl_debug_supervisor().spawn_once(format!("pl-debug-operation:{}:{id}", entry.id), move |_| async move {
let result =
with_credential_owner(task_entry.credential_owner.clone(), run_control(&task_entry, &request, generation))
.await;
finish_operation(&task_entry, &request.operation_id, generation, result);
}) {
finish_operation(
&entry,
&id,
generation,
Err(local_failure("application_closed", "The application is shutting down", false)),
);
}
}
async fn run_control(entry: &Entry, request: &PlDebugOperation, generation: u64) -> Result<Value, Value> {
if request.action.may_write() {
let state = entry
.app
.upgrade()
.ok_or_else(|| local_failure("application_closed", "Application state is no longer available", false))?;
check_write_protection(&state, entry, request.production_confirmed)
.await
.map_err(|error| local_failure("write_protected", error, false))?;
}
let (channel, agent_id, effective_stop_revision) = {
let mut data = entry.lock();
let serial = data.operations[&request.operation_id].control_serial;
if data.generation != generation || data.close.is_some() || data.access_revoked || serial != data.control_serial
{
return Err(local_failure("operation_superseded", "The operation was stopped before dispatch", false));
}
let channel = data
.channel
.clone()
.ok_or_else(|| local_failure("session_not_ready", "The original Agent session is not ready", false))?;
if request.action.may_write() && data.lifecycle.cancellation().is_cancelled() {
return Err(local_failure(
"connection_changed",
"The original connection was disconnected or changed",
false,
));
}
let operation = data.operations.get_mut(&request.operation_id).unwrap();
operation.receipt.state = OperationState::Running;
operation.receipt.dispatched = true;
let effective_stop_revision = operation.effective_stop_revision;
(channel, data.agent_id.clone(), effective_stop_revision)
};
let mut params = request.params.clone();
if let Some(revision) = effective_stop_revision {
params.as_object_mut().unwrap().insert("stopRevision".into(), json!(revision));
}
params.as_object_mut().unwrap().insert("debugId".into(), json!(agent_id));
params.as_object_mut().unwrap().insert("operationId".into(), json!(request.operation_id));
channel.call(request.action.method(), params, request.action.timeout(), None).await.map_err(call_failure)
}
pub async fn pl_debug_read_core(
state: &AppState,
access: &PlDebugAccess,
request: PlDebugRead,
) -> Result<Value, String> {
let entry = state.pl_debug.find(access, &request.session)?;
if matches!(request.kind, PlDebugReadKind::Results | PlDebugReadKind::ResultPage) {
return results::read(&entry, request).await;
}
let (channel, agent_id, serial, retained) = {
let data = entry.lock();
if data.generation != request.generation {
return Err("The debug generation changed; refresh before reading".into());
}
if request.kind.needs_stop()
&& (data.snapshot["state"] != "paused"
|| data.active_operation.is_some()
|| data.interrupt_operation.is_some()
|| request.stop_revision.is_none()
|| request.stop_revision != data.snapshot["stopRevision"].as_u64()
|| data.close.is_some())
{
return Err("The requested debug stop is no longer current".into());
}
(data.channel.clone(), data.agent_id.clone(), data.control_serial, data.retained_log.clone())
};
if let Some(log) = retained {
match request.kind {
PlDebugReadKind::Log => return Ok(log),
PlDebugReadKind::LogPage => return retained_log_page(&log, &request.params),
_ => {}
}
}
let channel = channel.ok_or("The original Agent session is not ready")?;
let mut params = request.params;
let object = params.as_object_mut().ok_or("Debug read parameters must be an object")?;
object.insert("debugId".into(), json!(agent_id));
if request.kind.needs_stop() {
object.insert("stopRevision".into(), json!(request.stop_revision));
}
let result = channel
.call::<Value>(request.kind.method(), params, QUICK_TIMEOUT, None)
.await
.map_err(|error| error.into_legacy_string())?;
let data = entry.lock();
if data.generation != request.generation
|| data.control_serial != serial
|| (request.kind.needs_stop() && result["stopRevision"].as_u64() != request.stop_revision)
{
return Err("The read completed for an old debug stop; refresh the current frame".into());
}
Ok(result)
}
fn retained_log_page(log: &Value, params: &Value) -> Result<Value, String> {
let text = log["output"].as_str().unwrap_or("");
let number = |key: &str, default: u64| -> Result<usize, String> {
params
.get(key)
.map_or(Ok(default), |v| v.as_u64().ok_or_else(|| format!("Invalid output {key}")))
.and_then(|v| usize::try_from(v).map_err(|_| format!("Invalid output {key}")))
};
let offset = number("offset", 0)?;
let limit = number("limit", 32000)?;
if !(2..=65536).contains(&limit) {
return Err("Invalid output page size".into());
}
let total = text.encode_utf16().count();
if offset > total {
return Err("Invalid output cursor".into());
}
let mut units = 0;
let mut begin = None;
let mut end = text.len();
let mut next = total;
for (byte, character) in text.char_indices() {
if units == offset {
begin = Some(byte);
}
if units < offset && units + character.len_utf16() > offset {
return Err("Output cursor splits a Unicode character".into());
}
if units >= offset && units + character.len_utf16() > offset + limit {
end = byte;
next = units;
break;
}
units += character.len_utf16();
}
let begin = begin.unwrap_or(text.len());
let mut result = log.clone();
result.as_object_mut().unwrap().remove("output");
result["outputPage"] = json!({"text":&text[begin..end],"offset":offset,"nextOffset":next,"totalChars":total,
"complete":log["outputComplete"],"truncated":log["outputTruncated"],"error":log["outputError"]});
Ok(result)
}
mod compilation;
pub use compilation::{
pl_debug_compile_core, pl_debug_compile_status_core, pl_debug_prepare_compile_core, pl_debug_submit_compile_core,
PlDebugCompile, PlDebugCompileAdmission, PlDebugCompileRef,
};
mod inspection;
mod lifecycle;
mod mutation;
mod results;
mod transport;
pub(crate) use inspection::InspectionOwner;
pub use inspection::{
pl_debug_inspect_dispatch_core, pl_debug_prepare_inspection_core, pl_debug_submit_inspection_core,
PlDebugInspectionAdmission, PlDebugInspectionSubmission,
};
pub(crate) use lifecycle::{begin_shutdown, drain_connection, drain_transport};
use lifecycle::{confirm_exit, request_close, spawn_watchdog};
pub use mutation::pl_debug_claim_mutation_core;
pub(crate) use transport::{
adopt_published_transport, current_transport, reserve_transport, retire_transport, transport_publication_guard,
};
#[cfg(test)]
mod tests;