zlayer-sdk 0.11.19

ZLayer Plugin Development Kit for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

/// ZLayer Plugin System - Shared Types
///
/// Common type definitions used across all ZLayer interfaces.
/// These types provide a consistent API surface for plugins.

/// Common types shared across all ZLayer interfaces
interface common {
    /// A key-value pair for metadata, headers, environment, etc.
    record key-value {
        key: string,
        value: string,
    }

    /// Timestamp in nanoseconds since Unix epoch
    type timestamp = u64;

    /// Duration in nanoseconds
    type duration = u64;

    /// Generic error with code and message
    record error {
        code: string,
        message: string,
    }
}

/// Plugin metadata types
interface plugin-metadata {
    use common.{key-value};

    /// Plugin version following semver
    record version {
        major: u32,
        minor: u32,
        patch: u32,
        pre-release: option<string>,
    }

    /// Plugin information returned by info()
    record plugin-info {
        /// Unique plugin identifier (e.g., "zlayer:auth-jwt")
        id: string,
        /// Human-readable name
        name: string,
        /// Plugin version
        version: version,
        /// Brief description of plugin functionality
        description: string,
        /// Plugin author or organization
        author: string,
        /// License identifier (e.g., "MIT", "Apache-2.0")
        license: option<string>,
        /// Homepage or repository URL
        homepage: option<string>,
        /// Additional metadata as key-value pairs
        metadata: list<key-value>,
    }

    /// Plugin capabilities that can be requested
    flags capabilities {
        /// Access to configuration values
        config,
        /// Access to key-value storage
        keyvalue,
        /// Ability to emit logs
        logging,
        /// Access to secrets management
        secrets,
        /// Ability to emit metrics
        metrics,
        /// Ability to make HTTP requests
        http-client,
    }
}

/// Request and response types for plugin handlers
interface request-types {
    use common.{key-value, timestamp};

    /// HTTP method enum
    enum http-method {
        get,
        post,
        put,
        delete,
        patch,
        head,
        options,
        connect,
        trace,
    }

    /// Incoming request to be processed by a plugin
    record plugin-request {
        /// Unique request identifier for tracing
        request-id: string,
        /// Request path (e.g., "/api/users/123")
        path: string,
        /// HTTP method
        method: http-method,
        /// Query string (without leading ?)
        query: option<string>,
        /// Request headers
        headers: list<key-value>,
        /// Request body as bytes (empty for GET/HEAD)
        body: list<u8>,
        /// Request timestamp
        timestamp: timestamp,
        /// Additional context from the host
        context: list<key-value>,
    }

    /// Plugin response returned to the host
    record plugin-response {
        /// HTTP status code (200, 404, 500, etc.)
        status: u16,
        /// Response headers
        headers: list<key-value>,
        /// Response body
        body: list<u8>,
    }

    /// Result of handling a request
    variant handle-result {
        /// Successfully handled, return response
        response(plugin-response),
        /// Plugin declined to handle, pass to next handler
        pass-through,
        /// Plugin encountered an error
        error(string),
    }
}