alien_sdk/
lib.rs

1//! Alien SDK for Rust.
2//!
3//! Cloud-agnostic bindings for storage, KV, queues, vaults, and linked containers, 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 kinds applications use directly:
9//! [`Storage`], [`Kv`], [`Queue`], [`Vault`], and [`Container`].
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, 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::{
65    Bindings, BoundQueue as Queue, Container, ErrorData, Kv, Result, Storage, Vault,
66};
67
68/// Errors returned by the application binding and Worker APIs.
69pub mod error {
70    pub use alien_bindings::error::{Error, ErrorData, Result};
71}
72
73/// Serializable requests returned by storage presigning operations.
74pub mod presigned {
75    pub use alien_bindings::presigned::{
76        LocalOperation, PresignedOperation, PresignedRequest, PresignedRequestBackend,
77        PresignedResponse,
78    };
79}
80
81/// App-facing binding value types (the option/message/result types that flow
82/// through storage/KV/queue/vault/container calls).
83pub mod traits {
84    pub use alien_bindings::traits::{
85        Kv, MessagePayload, PutOptions, QueueMessage, ScanResult, Storage, Vault,
86    };
87    pub use alien_bindings::{BoundQueue as Queue, Container};
88}
89
90#[cfg(feature = "worker")]
91mod alien_context;
92#[cfg(feature = "worker")]
93mod wait_until;
94
95/// Worker-only task, event, lifecycle, and `waitUntil` APIs.
96#[cfg(feature = "worker")]
97pub mod worker {
98    //! Worker task, event, lifecycle, and `waitUntil` APIs.
99    //!
100    //! `AlienContext` exposes the same application [`Bindings`]
101    //! facade, not the internal provider API:
102    //!
103    //! ```compile_fail
104    //! fn load_internal_binding(ctx: &alien_sdk::worker::AlienContext) {
105    //!     let _ = ctx.bindings().load_build("builder");
106    //! }
107    //! ```
108    //!
109    //! ```compile_fail
110    //! fn inspect_managed_resource(ctx: &alien_sdk::worker::AlienContext) {
111    //!     let _ = ctx.get_current_worker();
112    //!     let _ = ctx.get_current_container();
113    //! }
114    //! ```
115
116    pub use crate::alien_context::{AlienContext, CronEvent, QueueMessage, StorageEvent};
117    pub use crate::wait_until::{DrainConfig, DrainResponse, WaitUntil, WaitUntilContext};
118}
alien_sdk/lib.rs

alien_sdk/
lib.rs
