alien_sdk/
lib.rs

1//! Alien SDK for Rust.
2//!
3//! Cloud-agnostic bindings for storage, KV, queues, and vaults, plus the
4//! Worker application context.
5//! Works on AWS, GCP, Azure, Kubernetes, and locally.
6//!
7//! This is the public-facing crate for Alien app developers. Its binding API is
8//! deliberately limited to [`Bindings`] and the four kinds applications can
9//! use directly: [`Storage`], [`Kv`], [`Queue`], and [`Vault`].
10//!
11//! Platform tooling that needs provider construction or managed resource kinds
12//! such as builds and artifact registries uses `alien_bindings` directly.
13//! Worker applications enable the `worker` Cargo feature and use the
14//! `worker` module for task, event, lifecycle, and `waitUntil` APIs. The
15//! feature is not enabled by default, so direct-binding-only applications do
16//! not depend on the Worker protocol.
17//!
18//! # Example
19//!
20//! ```no_run
21//! use alien_sdk::Bindings;
22//!
23//! #[tokio::main(flavor = "current_thread")]
24//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
25//!     let bindings = Bindings::from_env()?;
26//!     let cache = bindings.kv("cache").await?;
27//!     cache.put("greeting", b"hello".to_vec(), None).await?;
28//!     assert_eq!(cache.get("greeting").await?, Some(b"hello".to_vec()));
29//!     Ok(())
30//! }
31//! ```
32//!
33//! Provider construction and managed resource bindings are not part of this
34//! crate's application API:
35//!
36//! ```compile_fail
37//! use alien_sdk::BindingsProvider;
38//! ```
39//!
40//! ```compile_fail
41//! use alien_sdk::BindingsProviderApi;
42//! ```
43//!
44//! ```compile_fail
45//! use alien_sdk::Binding;
46//! ```
47//!
48//! ```compile_fail
49//! use alien_sdk::{ArtifactRegistry, Build, Container, Postgres, ServiceAccount, Worker};
50//! ```
51//!
52//! ```compile_fail
53//! use alien_sdk::provider;
54//! ```
55//!
56//! ```compile_fail
57//! use alien_sdk::providers;
58//! ```
59//!
60//! ```compile_fail
61//! use alien_sdk::http_client;
62//! ```
63//!
64pub use alien_bindings::{Bindings, ErrorData, Kv, Queue, Result, Storage, Vault};
65
66/// Errors returned by the application binding and Worker APIs.
67pub mod error {
68    pub use alien_bindings::error::{Error, ErrorData, Result};
69}
70
71/// Serializable requests returned by storage presigning operations.
72pub mod presigned {
73    pub use alien_bindings::presigned::{
74        LocalOperation, PresignedOperation, PresignedRequest, PresignedRequestBackend,
75        PresignedResponse,
76    };
77}
78
79/// App-facing binding value types (the option/message/result types that flow
80/// through storage/KV/queue/vault calls).
81pub mod traits {
82    pub use alien_bindings::traits::{
83        Kv, MessagePayload, PutOptions, Queue, QueueMessage, ScanResult, Storage, Vault,
84    };
85}
86
87#[cfg(feature = "worker")]
88mod alien_context;
89#[cfg(feature = "worker")]
90mod wait_until;
91
92/// Worker-only task, event, lifecycle, and `waitUntil` APIs.
93#[cfg(feature = "worker")]
94pub mod worker {
95    //! Worker task, event, lifecycle, and `waitUntil` APIs.
96    //!
97    //! `AlienContext` exposes the same four-kind application [`Bindings`]
98    //! facade, not the internal provider API:
99    //!
100    //! ```compile_fail
101    //! fn load_internal_binding(ctx: &alien_sdk::worker::AlienContext) {
102    //!     let _ = ctx.bindings().load_build("builder");
103    //! }
104    //! ```
105    //!
106    //! ```compile_fail
107    //! fn inspect_managed_resource(ctx: &alien_sdk::worker::AlienContext) {
108    //!     let _ = ctx.get_current_worker();
109    //!     let _ = ctx.get_current_container();
110    //! }
111    //! ```
112
113    pub use crate::alien_context::{AlienContext, CronEvent, QueueMessage, StorageEvent};
114    pub use crate::wait_until::{DrainConfig, DrainResponse, WaitUntil, WaitUntilContext};
115}
alien_sdk/lib.rs

alien_sdk/
lib.rs
