Trait GraphQlTargetPlugin 

pub trait GraphQlTargetPlugin: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn endpoint(&self) -> &str;

    // Provided methods
    fn version_headers(&self) -> HashMap<String, String> { ... }
    fn default_auth(&self) -> Option<GraphQlAuth> { ... }
    fn default_page_size(&self) -> usize { ... }
    fn supports_cursor_pagination(&self) -> bool { ... }
    fn description(&self) -> &str { ... }
    fn cost_throttle_config(&self) -> Option<CostThrottleConfig> { ... }
    fn rate_limit_config(&self) -> Option<RateLimitConfig> { ... }
}

A named GraphQL target that supplies connection defaults for a specific API.

Plugins are identified by their name and loaded from the GraphQlPluginRegistry at pipeline execution time.

Example

use std::collections::HashMap;
use stygian_graph::ports::graphql_plugin::GraphQlTargetPlugin;
use stygian_graph::ports::{GraphQlAuth, GraphQlAuthKind};

struct MyApiPlugin;

impl GraphQlTargetPlugin for MyApiPlugin {
    fn name(&self) -> &str { "my-api" }
    fn endpoint(&self) -> &str { "https://api.example.com/graphql" }
    fn version_headers(&self) -> HashMap<String, String> {
        [("X-API-VERSION".to_string(), "2025-01-01".to_string())].into()
    }
    fn default_auth(&self) -> Option<GraphQlAuth> { None }
}

Required Methods

fn name(&self) -> &str

Canonical lowercase plugin name used in pipeline TOML: plugin = "jobber".

fn endpoint(&self) -> &str

The GraphQL endpoint URL for this target.

Used as the request URL when ServiceInput.url is empty.

Provided Methods

fn version_headers(&self) -> HashMap<String, String>

Version or platform headers required by this API.

Injected on every request. Plugin headers take precedence over ad-hoc params.headers for the same key.

Example

use std::collections::HashMap;
use stygian_graph::ports::graphql_plugin::GraphQlTargetPlugin;
use stygian_graph::ports::{GraphQlAuth, GraphQlAuthKind};

struct JobberPlugin;
impl GraphQlTargetPlugin for JobberPlugin {
    fn name(&self) -> &str { "jobber" }
    fn endpoint(&self) -> &str { "https://api.getjobber.com/api/graphql" }
    fn version_headers(&self) -> HashMap<String, String> {
        [("X-JOBBER-GRAPHQL-VERSION".to_string(), "2025-04-16".to_string())].into()
    }
}

fn default_auth(&self) -> Option<GraphQlAuth>

Default auth to use when params.auth is absent.

Implementations should read credentials from environment variables here.

Example

use std::collections::HashMap;
use stygian_graph::ports::graphql_plugin::GraphQlTargetPlugin;
use stygian_graph::ports::{GraphQlAuth, GraphQlAuthKind};

struct SecurePlugin;
impl GraphQlTargetPlugin for SecurePlugin {
    fn name(&self) -> &str { "secure" }
    fn endpoint(&self) -> &str { "https://api.secure.com/graphql" }
    fn default_auth(&self) -> Option<GraphQlAuth> {
        Some(GraphQlAuth {
            kind: GraphQlAuthKind::Bearer,
            token: "${env:SECURE_ACCESS_TOKEN}".to_string(),
            header_name: None,
        })
    }
}

fn default_page_size(&self) -> usize

Default page size for cursor-paginated queries.

fn supports_cursor_pagination(&self) -> bool

Whether this target uses Relay-style cursor pagination by default.

fn description(&self) -> &str

Human-readable description shown in stygian plugins list.

fn cost_throttle_config(&self) -> Option<CostThrottleConfig>

Optional cost-throttle configuration for proactive pre-flight delays.

Return a populated CostThrottleConfig to enable the PluginBudget pre-flight delay mechanism in GraphQlService.

The default implementation returns None (no proactive throttling).

Example

use std::collections::HashMap;
use stygian_graph::ports::graphql_plugin::{GraphQlTargetPlugin, CostThrottleConfig};
use stygian_graph::ports::GraphQlAuth;

struct ThrottledPlugin;
impl GraphQlTargetPlugin for ThrottledPlugin {
    fn name(&self) -> &str { "throttled" }
    fn endpoint(&self) -> &str { "https://api.example.com/graphql" }
    fn cost_throttle_config(&self) -> Option<CostThrottleConfig> {
        Some(CostThrottleConfig::default())
    }
}

fn rate_limit_config(&self) -> Option<RateLimitConfig>

Optional sliding-window request-count rate-limit configuration.

Return a populated RateLimitConfig to enable the RequestRateLimit pre-flight delay mechanism in GraphQlService.

The default implementation returns None (no request-count limiting).

Example

use std::collections::HashMap;
use std::time::Duration;
use stygian_graph::ports::graphql_plugin::{GraphQlTargetPlugin, RateLimitConfig};
use stygian_graph::ports::GraphQlAuth;

struct QuotaPlugin;
impl GraphQlTargetPlugin for QuotaPlugin {
    fn name(&self) -> &str { "quota" }
    fn endpoint(&self) -> &str { "https://api.example.com/graphql" }
    fn rate_limit_config(&self) -> Option<RateLimitConfig> {
        Some(RateLimitConfig {
            max_requests: 200,
            window: Duration::from_secs(60),
            max_delay_ms: 30_000,
            ..Default::default()
        })
    }
}

Implementors

impl GraphQlTargetPlugin for GenericGraphQlPlugin