feat(api, web-scraper): add support for debug endpoints

Author: azasypkin

.github/workflows/ci.yml

@@ -63,7 +63,7 @@ jobs:
 
       - name: Test (default features)
         timeout-minutes: 6
-        run: cargo test -- --nocapture
+        run: cargo test --all -- --nocapture
 
       - name: Check database schema
         run: cargo sqlx prepare --check

components/retrack-types/src/trackers.rs

@@ -4,6 +4,9 @@ mod tracker_config;
 mod tracker_create_params;
 mod tracker_data_revision;
 mod tracker_data_value;
+mod tracker_debug_existing_params;
+mod tracker_debug_params;
+mod tracker_debug_result;
 mod tracker_list_revisions_params;
 mod tracker_target;
 mod tracker_update_params;
@@ -19,6 +22,14 @@ pub use self::{
     tracker_create_params::TrackerCreateParams,
     tracker_data_revision::TrackerDataRevision,
     tracker_data_value::TrackerDataValue,
+    tracker_debug_existing_params::TrackerDebugExistingParams,
+    tracker_debug_params::TrackerDebugParams,
+    tracker_debug_result::{
+        ActionDebugInfo, ActionDestinationDebugInfo, ApiRequestDebugInfo, ApiTrackerDebugResult,
+        AutoParseDebugInfo, EmailDestinationDebugInfo, PageLogEntry, PageTrackerDebugResult,
+        RenderedEmailDebugInfo, ScriptDebugInfo, TrackerDebugResult, TrackerDebugTargetResult,
+        WebhookDestinationDebugInfo,
+    },
     tracker_list_revisions_params::{
         DEFAULT_DIFF_CONTEXT_RADIUS, MAX_DIFF_CONTEXT_RADIUS, TrackerListRevisionsParams,
     },

components/retrack-types/src/trackers/tracker_debug_existing_params.rs

@@ -0,0 +1,101 @@
+use crate::trackers::{TrackerAction, TrackerConfig, TrackerDataValue, TrackerTarget};
+use serde::{Deserialize, Serialize};
+use serde_with::skip_serializing_none;
+use utoipa::ToSchema;
+
+/// Parameters for the existing-tracker debug endpoint
+/// (`POST /api/trackers/{tracker_id}/_debug`).
+///
+/// Every field is optional. When provided, it overrides the corresponding field on the
+/// stored tracker for this debug run only (nothing is persisted).
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct TrackerDebugExistingParams {
+    /// Override the tracker's target for this debug run.
+    pub target: Option<TrackerTarget>,
+    /// Override the tracker's config for this debug run.
+    pub config: Option<TrackerConfig>,
+    /// Override the tracker's tags for this debug run.
+    pub tags: Option<Vec<String>>,
+    /// Override the tracker's actions for this debug run.
+    pub actions: Option<Vec<TrackerAction>>,
+    /// Supply previous content instead of using the latest stored revision.
+    pub previous_content: Option<TrackerDataValue>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::TrackerDebugExistingParams;
+    use crate::trackers::{PageTarget, TrackerDataValue, TrackerTarget};
+    use insta::assert_json_snapshot;
+    use serde_json::json;
+
+    #[test]
+    fn deserialization_empty() -> anyhow::Result<()> {
+        let params: TrackerDebugExistingParams = serde_json::from_value(json!({}))?;
+        assert_eq!(params, TrackerDebugExistingParams::default());
+        Ok(())
+    }
+
+    #[test]
+    fn deserialization_with_overrides() -> anyhow::Result<()> {
+        let params: TrackerDebugExistingParams = serde_json::from_value(json!({
+            "target": {
+                "type": "page",
+                "extractor": "export async function execute(p) { return 'ok'; }"
+            },
+            "tags": ["override-tag"],
+            "previousContent": { "original": "prev" }
+        }))?;
+
+        assert!(params.target.is_some());
+        assert!(params.config.is_none());
+        assert_eq!(params.tags, Some(vec!["override-tag".to_string()]));
+        assert!(params.actions.is_none());
+        assert_eq!(
+            params.previous_content,
+            Some(TrackerDataValue::new(json!("prev")))
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn serialization_roundtrip() -> anyhow::Result<()> {
+        let params = TrackerDebugExistingParams {
+            target: Some(TrackerTarget::Page(PageTarget {
+                extractor: "script".to_string(),
+                params: None,
+                engine: None,
+                user_agent: None,
+                accept_invalid_certificates: false,
+            })),
+            config: None,
+            tags: Some(vec!["t".to_string()]),
+            actions: None,
+            previous_content: Some(TrackerDataValue::new(json!("prev"))),
+        };
+
+        assert_json_snapshot!(params, @r###"
+        {
+          "target": {
+            "type": "page",
+            "extractor": "script"
+          },
+          "tags": [
+            "t"
+          ],
+          "previousContent": {
+            "original": "prev"
+          }
+        }
+        "###);
+
+        let roundtrip: TrackerDebugExistingParams =
+            serde_json::from_value(serde_json::to_value(&params)?)?;
+        assert_eq!(roundtrip, params);
+
+        Ok(())
+    }
+}

components/retrack-types/src/trackers/tracker_debug_params.rs

@@ -0,0 +1,141 @@
+use crate::trackers::{TrackerAction, TrackerConfig, TrackerDataValue, TrackerTarget};
+use serde::{Deserialize, Serialize};
+use serde_with::skip_serializing_none;
+use utoipa::ToSchema;
+
+/// Parameters for the ad-hoc tracker debug endpoint (`POST /api/trackers/_debug`).
+///
+/// Accepts the same target/config shape as `TrackerCreateParams` but does not persist
+/// anything. Fields irrelevant to a debug run (schedule, revisions count) are accepted
+/// but ignored.
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct TrackerDebugParams {
+    /// Target of the tracker (web page or API).
+    pub target: TrackerTarget,
+    /// Tracker config (only `timeout` is meaningful for debug runs).
+    #[serde(default)]
+    pub config: TrackerConfig,
+    /// Tracker tags.
+    #[serde(default)]
+    pub tags: Vec<String>,
+    /// Actions to simulate (dry-run). No side-effects are produced.
+    #[serde(default)]
+    pub actions: Vec<TrackerAction>,
+    /// Optional previous content to simulate how the tracker behaves with existing data.
+    pub previous_content: Option<TrackerDataValue>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::TrackerDebugParams;
+    use crate::trackers::{
+        PageTarget, TrackerAction, TrackerConfig, TrackerDataValue, TrackerTarget, WebhookAction,
+    };
+    use insta::assert_json_snapshot;
+    use serde_json::json;
+    use std::time::Duration;
+
+    #[test]
+    fn deserialization_minimal() -> anyhow::Result<()> {
+        let params: TrackerDebugParams = serde_json::from_value(json!({
+            "target": {
+                "type": "page",
+                "extractor": "export async function execute(p) { return 'ok'; }"
+            }
+        }))?;
+
+        assert_eq!(
+            params.target,
+            TrackerTarget::Page(PageTarget {
+                extractor: "export async function execute(p) { return 'ok'; }".to_string(),
+                params: None,
+                engine: None,
+                user_agent: None,
+                accept_invalid_certificates: false,
+            })
+        );
+        assert_eq!(params.config, TrackerConfig::default());
+        assert!(params.tags.is_empty());
+        assert!(params.actions.is_empty());
+        assert!(params.previous_content.is_none());
+
+        Ok(())
+    }
+
+    #[test]
+    fn deserialization_full() -> anyhow::Result<()> {
+        let params: TrackerDebugParams = serde_json::from_value(json!({
+            "target": {
+                "type": "page",
+                "extractor": "export async function execute(p) { return 'ok'; }"
+            },
+            "config": { "revisions": 1, "timeout": 5000 },
+            "tags": ["t1"],
+            "actions": [{ "type": "webhook", "url": "https://retrack.dev/" }],
+            "previousContent": { "original": "prev" }
+        }))?;
+
+        assert_eq!(params.config.timeout, Some(Duration::from_millis(5000)));
+        assert_eq!(params.tags, vec!["t1"]);
+        assert_eq!(params.actions.len(), 1);
+        assert_eq!(
+            params.previous_content,
+            Some(TrackerDataValue::new(json!("prev")))
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn serialization_roundtrip() -> anyhow::Result<()> {
+        let params = TrackerDebugParams {
+            target: TrackerTarget::Page(PageTarget {
+                extractor: "script".to_string(),
+                params: None,
+                engine: None,
+                user_agent: None,
+                accept_invalid_certificates: false,
+            }),
+            config: TrackerConfig::default(),
+            tags: vec!["tag".to_string()],
+            actions: vec![TrackerAction::Webhook(WebhookAction {
+                url: "https://retrack.dev".parse()?,
+                method: None,
+                headers: None,
+                formatter: None,
+            })],
+            previous_content: Some(TrackerDataValue::new(json!("prev"))),
+        };
+
+        assert_json_snapshot!(params, @r###"
+        {
+          "target": {
+            "type": "page",
+            "extractor": "script"
+          },
+          "config": {
+            "revisions": 3
+          },
+          "tags": [
+            "tag"
+          ],
+          "actions": [
+            {
+              "type": "webhook",
+              "url": "https://retrack.dev/"
+            }
+          ],
+          "previousContent": {
+            "original": "prev"
+          }
+        }
+        "###);
+
+        let roundtrip: TrackerDebugParams = serde_json::from_value(serde_json::to_value(&params)?)?;
+        assert_eq!(roundtrip, params);
+
+        Ok(())
+    }
+}