rusty_cdk_core/wrappers/
mod.rs

1//! Type-safe wrapper types
2//!
3//! This module provides newtype wrappers that enforce type safety and validation
4//! for various configuration values used in AWS resources. These wrappers help
5//! prevent common mistakes like using invalid identifiers, zero values where
6//! positive numbers are required, or invalid memory/timeout configurations.
7//!
8//! # Creating Wrappers
9//! 
10//! ** Recommended approach: ** Use the compile-time validated proc macros from the
11//! `rusty-cdk-macros` crate for type safety and validation at compile time.
12//! 
13//! ** Direct creation: ** While these wrappers can be created directly by calling
14//! their constructors, this bypasses compile-time validation and should only be
15//! used as an override.
16//!
17//! # Example
18//! ```rust
19//! use rusty_cdk_core::wrappers::StringWithOnlyAlphaNumericsAndUnderscores;
20//! use rusty_cdk_macros::string_with_only_alphanumerics_and_underscores;
21//! use rusty_cdk_core::wrappers::{Memory};
22//!
23//! // Preferred: Use the macro for compile-time validation
24//! let function_name = string_with_only_alphanumerics_and_underscores!("my_lambda_function");
25//! ```
26
27/// A string wrapper that ensures the content contains only letters, numbers, and underscores.
28///
29/// # Validation Rules (when using the macro)
30/// - Only alphanumeric characters (a-z, A-Z, 0-9) and underscores (_) are allowed
31///
32/// # Recommended Usage
33/// Use the `string_with_only_alphanumerics_and_underscores!` macro from `rusty-cdk-macros`
34/// for compile-time validation:
35///
36/// ```rust
37/// use rusty_cdk_core::wrappers::StringWithOnlyAlphaNumericsAndUnderscores;
38/// use rusty_cdk_macros::string_with_only_alphanumerics_and_underscores;
39///
40/// let function_name = string_with_only_alphanumerics_and_underscores!("my_lambda_function");
41/// ```
42#[derive(Debug, Clone)]
43pub struct StringWithOnlyAlphaNumericsAndUnderscores(pub String);
44
45/// A string wrapper that ensures the content contains only letters, numbers, underscores, and hyphens.
46///
47/// # Validation Rules (when using the macro)
48/// - Only alphanumeric characters (a-z, A-Z, 0-9), underscores (_), and hyphens (-) are allowed
49///
50/// # Recommended Usage
51/// Use the `string_with_only_alphanumerics_underscores_and_hyphens!` macro from `rusty-cdk-macros`
52/// for compile-time validation:
53///
54/// ```rust
55/// use rusty_cdk_core::wrappers::StringWithOnlyAlphaNumericsUnderscoresAndHyphens;
56/// use rusty_cdk_macros::string_with_only_alphanumerics_underscores_and_hyphens;
57///
58/// let stack_name = string_with_only_alphanumerics_underscores_and_hyphens!("my-function-name");
59/// ```
60#[derive(Debug, Clone)]
61pub struct StringWithOnlyAlphaNumericsUnderscoresAndHyphens(pub String);
62
63/// A string wrapper that ensures the content contains only letters, numbers, and hyphens.
64///
65/// # Validation Rules (when using the macro)
66/// - Only alphanumeric characters (a-z, A-Z, 0-9), underscores (_), and hyphens (-) are allowed
67///
68/// # Recommended Usage
69/// Use the `string_with_only_alphanumerics_underscores_and_hyphens!` macro from `rusty-cdk-macros`
70/// for compile-time validation:
71///
72/// ```rust
73/// use rusty_cdk_core::wrappers::StringWithOnlyAlphaNumericsAndHyphens;
74/// use rusty_cdk_macros::string_with_only_alphanumerics_and_hyphens;
75///
76/// let stack_name = string_with_only_alphanumerics_and_hyphens!("my-stack-name");
77/// ```
78#[derive(Debug, Clone)]
79pub struct StringWithOnlyAlphaNumericsAndHyphens(pub String);
80
81/// A string wrapper for AWS Secrets Manager secret names.
82///
83/// # Validation Rules (when using the macro)
84/// - String must not be empty
85/// - Only alphanumeric characters and the following special characters are allowed: / _ + = . @ -
86/// - Maximum length of 512 characters (AWS Secrets Manager limit)
87///
88/// # Recommended Usage
89/// Use the `string_for_secret!` macro from `rusty-cdk-macros` for compile-time validation:
90///
91/// ```rust
92/// use rusty_cdk_core::wrappers::StringForSecret;
93/// use rusty_cdk_macros::string_for_secret;
94///
95/// let secret_name = string_for_secret!("myapp/database/password");
96/// ```
97#[derive(Debug, Clone)]
98pub struct StringForSecret(pub String);
99
100/// A wrapper for positive integers that must be greater than zero.
101///
102/// # Recommended Usage
103/// Use the `non_zero_number!` macro from `rusty-cdk-macros` for compile-time validation:
104///
105/// ```rust
106/// use rusty_cdk_core::wrappers::NonZeroNumber;
107/// use rusty_cdk_macros::non_zero_number;
108/// 
109/// let capacity = non_zero_number!(10);
110/// ```
111#[derive(Debug, Copy, Clone)]
112pub struct NonZeroNumber(pub u32);
113
114/// Memory allocation configuration for AWS Lambda functions, specified in megabytes.
115///
116/// # Validation Rules (when using the macro)
117/// - Minimum: 128 MB
118/// - Maximum: 10,240 MB (10 GB)
119///
120/// # Recommended Usage
121/// Use the `memory!` macro from `rusty-cdk-macros` for compile-time validation:
122///
123/// ```rust
124/// use rusty_cdk_core::wrappers::Memory;
125/// use rusty_cdk_macros::memory;
126/// 
127/// let mem = memory!(512);
128/// ```
129#[derive(Debug, Copy, Clone)]
130pub struct Memory(pub u16);
131
132/// Timeout configuration for AWS Lambda functions, specified in seconds.
133///
134/// # Validation Rules (when using the macro)
135/// - Minimum: 1 second
136/// - Maximum: 900 seconds (15 minutes)
137///
138/// # Recommended Usage
139/// Use the `timeout!` macro from `rusty-cdk-macros` for compile-time validation:
140///
141/// ```rust
142/// use rusty_cdk_core::wrappers::Timeout;
143/// use rusty_cdk_macros::timeout;
144/// 
145/// let timeout_val = timeout!(30);
146/// ```
147#[derive(Debug, Copy, Clone)]
148pub struct Timeout(pub u16);
149
150/// Environment variable key wrapper for AWS Lambda function configuration.
151///
152/// # Validation Rules (when using the macro)
153/// - Minimum length of 2
154/// - Should start with a letter of number
155/// - Should only contain letters, numbers and underscores
156///
157/// # Recommended Usage
158/// Use the `env_var_key!` macro from `rusty-cdk-macros` for compile-time validation:
159///
160/// ```rust
161/// use rusty_cdk_core::wrappers::EnvVarKey;
162/// use rusty_cdk_macros::env_var_key;
163/// 
164/// let db_url = env_var_key!("DATABASE_URL");
165/// ```
166#[derive(Debug, Clone)]
167pub struct EnvVarKey(pub String);
168
169/// File path wrapper for AWS Lambda deployment package ZIP files.
170///
171/// # Use Cases
172/// - Lambda function deployment packages
173/// - Any AWS resource requiring ZIP file uploads
174///
175/// # Validation Rules (when using the macro)
176/// - Should be a valid file path to a ZIP file
177/// - Can be relative or absolute paths
178/// - File should exist and be accessible at deployment time
179///
180/// # Recommended Usage
181/// Use the `zip_file!` macro from `rusty-cdk-macros` for compile-time validation:
182///
183/// ```rust,compile_fail
184/// use rusty_cdk_core::wrappers::ZipFile;
185/// use rusty_cdk_macros::zip_file;
186/// 
187/// let lambda_code = zip_file!("./target/lambda/function.zip");
188/// ```
189#[derive(Debug, Clone)]
190pub struct ZipFile(pub String);
191
192/// Delay seconds wrapper for AWS SQS queue configuration.
193///
194/// # Validation Rules (when using the macro)
195/// - Minimum: 0 seconds (no delay)
196/// - Maximum: 900 seconds (15 minutes)
197///
198/// # Recommended Usage
199/// Use the `delay_seconds!` macro from `rusty-cdk-macros` for compile-time validation:
200///
201/// ```rust
202/// use rusty_cdk_core::wrappers::DelaySeconds;
203/// use rusty_cdk_macros::delay_seconds;
204/// 
205/// let delay = delay_seconds!(300);
206/// ```
207#[derive(Debug, Copy, Clone)]
208pub struct DelaySeconds(pub u16);
209
210/// Maximum message size wrapper for AWS SQS queue configuration.
211///
212/// # Validation Rules (when using the macro)
213/// - Minimum: 1,024 bytes (1 KiB)
214/// - Maximum: 1,048,576 bytes (1 MiB)
215///
216/// # Recommended Usage
217/// Use the `maximum_message_size!` macro from `rusty-cdk-macros` for compile-time validation:
218///
219/// ```rust
220/// use rusty_cdk_core::wrappers::MaximumMessageSize;
221/// use rusty_cdk_macros::maximum_message_size;
222/// 
223/// let max_size = maximum_message_size!(262144); // 256 KiB
224/// ```
225#[derive(Debug, Copy, Clone)]
226pub struct MaximumMessageSize(pub u32);
227
228/// Message retention period wrapper for AWS SQS queue configuration.
229///
230/// # Validation Rules (when using the macro)
231/// - Minimum: 60 seconds (1 minute)
232/// - Maximum: 1,209,600 seconds (14 days)
233///
234/// # Recommended Usage
235/// Use the `message_retention_period!` macro from `rusty-cdk-macros` for compile-time validation:
236///
237/// ```rust
238/// use rusty_cdk_core::wrappers::MessageRetentionPeriod;
239/// use rusty_cdk_macros::message_retention_period;
240/// 
241/// let retention = message_retention_period!(345600); // 4 days
242/// ```
243#[derive(Debug, Copy, Clone)]
244pub struct MessageRetentionPeriod(pub u32);
245
246/// Visibility timeout wrapper for AWS SQS queue configuration.
247/// Determines how long messages remain invisible after being received by a consumer
248///
249/// # Validation Rules (when using the macro)
250/// - Minimum: 0 seconds
251/// - Maximum: 43,200 seconds (12 hours)
252///
253/// # Recommended Usage
254/// Use the `visibility_timeout!` macro from `rusty-cdk-macros` for compile-time validation:
255///
256/// ```rust
257/// use rusty_cdk_core::wrappers::VisibilityTimeout;
258/// use rusty_cdk_macros::visibility_timeout;
259/// 
260/// let timeout = visibility_timeout!(30);
261/// ```
262#[derive(Debug, Copy, Clone)]
263pub struct VisibilityTimeout(pub u32);
264
265/// Receive message wait time wrapper for AWS SQS queue configuration.
266///
267/// # Validation Rules (when using the macro)
268/// - Minimum: 0 seconds (short polling)
269/// - Maximum: 20 seconds (long polling)
270/// - Enables long polling when greater than 0
271///
272/// # Recommended Usage
273/// Use the `receive_message_wait_time!` macro from `rusty-cdk-macros` for compile-time validation:
274///
275/// ```rust
276/// use rusty_cdk_core::wrappers::ReceiveMessageWaitTime;
277/// use rusty_cdk_macros::receive_message_wait_time;
278/// 
279/// let wait_time = receive_message_wait_time!(10);
280/// ```
281#[derive(Debug, Copy, Clone)]
282pub struct ReceiveMessageWaitTime(pub u8);
283
284/// Maximum concurrency configuration for SQS event sources in AWS Lambda.
285///
286/// # Validation Rules (when using the macro)
287/// - Minimum: 2 concurrent invocations
288/// - Maximum: 1,000 concurrent invocations
289///
290/// # Recommended Usage
291/// Use the `sqs_event_source_max_concurrency!` macro from `rusty-cdk-macros` for compile-time validation:
292///
293/// ```rust
294/// use rusty_cdk_core::wrappers::SqsEventSourceMaxConcurrency;
295/// use rusty_cdk_macros::sqs_event_source_max_concurrency;
296///
297/// let max_concurrency = sqs_event_source_max_concurrency!(10);
298/// ```
299#[derive(Debug, Copy, Clone)]
300pub struct SqsEventSourceMaxConcurrency(pub u16);
301
302/// A wrapper for referencing existing AWS S3 buckets.
303///
304/// Use this when you need to reference a bucket that already exists, as opposed to creating a new one (use `BucketName` for new buckets).
305///
306/// # Validation Rules (when using the macro)
307/// - Value must not be an ARN (cannot start with "arn:")
308/// - Value must not include the "s3:" prefix
309/// - Bucket must exist in your AWS account
310///
311/// # Recommended Usage
312/// Use the `bucket!` macro from `rusty-cdk-macros` for compile-time validation
313///
314/// # Note
315/// The `bucket!` macro queries AWS at compile time to verify the bucket exists and caches the result for faster subsequent compilations. 
316/// Set `RUSTY_CDK_NO_REMOTE=true` env var to skip remote checks.
317#[derive(Debug, Clone)]
318pub struct Bucket(pub String);
319
320/// Retention period configuration for AWS CloudWatch Logs log groups, specified in days.
321///
322/// # Validation Rules (when using the macro)
323/// - Must be one of the following values:
324///   1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653
325///
326/// # Recommended Usage
327/// Use the `log_retention!` macro from `rusty-cdk-macros` for compile-time validation:
328///
329/// ```rust
330/// use rusty_cdk_core::wrappers::RetentionInDays;
331/// use rusty_cdk_macros::log_retention;
332///
333/// let retention = log_retention!(30);
334/// ```
335#[derive(Debug, Copy, Clone)]
336pub struct RetentionInDays(pub u16);
337
338/// A wrapper for AWS CloudWatch Logs log group names.
339///
340/// # Validation Rules (when using the macro)
341/// - String must not be empty
342/// - Maximum length of 512 characters
343/// - Only alphanumeric characters and the following special characters are allowed: . - _ # / \
344///
345/// # Recommended Usage
346/// Use the `log_group_name!` macro from `rusty-cdk-macros` for compile-time validation:
347///
348/// ```rust
349/// use rusty_cdk_core::wrappers::LogGroupName;
350/// use rusty_cdk_macros::log_group_name;
351///
352/// let log_group = log_group_name!("/aws/lambda/my-function");
353/// ```
354#[derive(Debug, Clone)]
355pub struct LogGroupName(pub String);
356
357/// A wrapper for creating new AWS S3 bucket names.
358///
359/// # Validation Rules (when using the macro)
360/// - Must contain only lowercase letters, numbers, periods (.), and hyphens (-)
361/// - No uppercase letters are allowed
362/// - Bucket name must be globally unique and available (verified at compile time)
363/// - Must be between 3 and 63 characters long
364///
365/// # Recommended Usage
366/// Use the `bucket_name!` macro from `rusty-cdk-macros` for compile-time validation
367///
368/// # Note
369/// The `bucket_name!` macro queries AWS at compile time to verify the bucket name is globally
370/// available and caches the result for faster subsequent compilations. 
371/// Set `RUSTY_CDK_NO_REMOTE=true` to skip remote checks.
372#[derive(Debug, Clone)]
373pub struct BucketName(pub String);
374
375/// A wrapper for AWS IAM action permissions.
376///
377/// This wrapper ensures type safety when defining IAM policy actions, helping prevent
378/// runtime IAM policy errors by validating permissions at compile time against AWS's
379/// official permission list.
380///
381/// # Validation Rules (when using the macro)
382/// - String must not be empty
383/// - Action must be a valid AWS IAM action (e.g., "s3:GetObject", "dynamodb:Query")
384/// - Wildcards are supported (e.g., "s3:*", "dynamodb:Get*")
385///
386/// # Recommended Usage
387/// Use the `iam_action!` macro from `rusty-cdk-macros` for compile-time validation:
388///
389/// ```rust
390/// use rusty_cdk_core::wrappers::IamAction;
391/// use rusty_cdk_macros::iam_action;
392///
393/// let action = iam_action!("s3:GetObject");
394/// let wildcard_action = iam_action!("s3:Put*");
395/// ```
396#[derive(Debug, Clone)]
397pub struct IamAction(pub String);
398
399/// Configuration for object size constraints in S3 lifecycle rules, specified in bytes.
400///
401/// This wrapper defines minimum and maximum object sizes for S3 lifecycle transitions.
402/// It allows you to apply lifecycle rules only to objects within a specific size range.
403///
404/// # Structure
405/// - First value: Minimum object size (optional)
406/// - Second value: Maximum object size (optional)
407/// - Both values are in bytes
408///
409/// # Validation Rules (when using the macro)
410/// - If both values are provided, the first must be smaller than the second
411/// - Values represent object sizes in bytes
412///
413/// # Recommended Usage
414/// Use the `lifecycle_object_sizes!` macro from `rusty-cdk-macros` for compile-time validation:
415///
416/// ```rust
417/// use rusty_cdk_core::wrappers::S3LifecycleObjectSizes;
418/// use rusty_cdk_macros::lifecycle_object_sizes;
419///
420/// let sizes = lifecycle_object_sizes!(1024,10485760);
421///
422/// let max_only = lifecycle_object_sizes!(5242880);
423/// ```
424#[derive(Debug, Clone)]
425pub struct S3LifecycleObjectSizes(pub Option<u32>, pub Option<u32>);
426
427/// A wrapper for TOML configuration file paths.
428///
429/// This wrapper ensures type safety when specifying paths to TOML configuration files used in infrastructure definitions.
430/// 
431/// # Recommended Usage
432/// Use the `toml_file!` macro from `rusty-cdk-macros` for compile-time validation
433#[derive(Debug, Clone)]
434pub struct TomlFile(pub String);
435
436/// Number of connection attempts for CloudFront origin connections.
437///
438/// # Validation Rules (when using the macro)
439/// - Minimum: 1 attempt
440/// - Maximum: 3 attempts
441/// - Determines retry behavior for origin connection failures
442///
443/// # Recommended Usage
444/// Use the `connection_attempts!` macro from `rusty-cdk-macros` for compile-time validation
445#[derive(Debug, Clone)]
446pub struct ConnectionAttempts(pub u8);
447
448/// Connection timeout configuration for CloudFront origins, specified in seconds.
449///
450/// # Structure
451/// - First value: Connection timeout in seconds (optional, 1-10 seconds)
452/// - Second value: Response completion timeout in seconds (optional, must be >= connection timeout)
453///
454/// # Recommended Usage
455/// Use the `cf_connection_timeout!` macro from `rusty-cdk-macros` for compile-time validation:
456///
457/// ```rust
458/// use rusty_cdk_core::wrappers::CfConnectionTimeout;
459/// use rusty_cdk_core::wrappers::S3LifecycleObjectSizes;
460/// use rusty_cdk_macros::cf_connection_timeout;
461///
462/// let timeouts = cf_connection_timeout!(5,30);
463///
464/// let conn_only = cf_connection_timeout!(3);
465/// ```
466#[derive(Debug, Clone)]
467pub struct CfConnectionTimeout(pub Option<u16>, pub Option<u16>);
468
469/// Path prefix for CloudFront origin requests.
470///
471/// # Recommended Usage
472/// Use the `origin_path!` macro from `rusty-cdk-macros` for compile-time validation
473#[derive(Debug, Clone)]
474pub struct OriginPath(pub String);
475
476/// Default root object for CloudFront distributions.
477///
478/// This wrapper specifies the object that CloudFront returns when a viewer requests
479/// the root URL of your distribution (e.g., http://example.com/ instead of http://example.com/index.html).
480/// 
481/// # Recommended Usage
482/// Use the `default_root_object!` macro from `rusty-cdk-macros` for compile-time validation
483#[derive(Debug, Clone)]
484pub struct DefaultRootObject(pub String);
485
486/// Read timeout for S3 origin in CloudFront, specified in seconds.
487///
488/// # Validation Rules (when using the macro)
489/// - Minimum: 1 second
490/// - Maximum: 120 seconds
491/// - Determines maximum wait time for S3 to respond
492///
493/// # Recommended Usage
494/// Use the `s3_origin_read_timeout!` macro from `rusty-cdk-macros` for compile-time validation
495#[derive(Debug, Clone)]
496pub struct S3OriginReadTimeout(pub u8);
497
498/// Action specification for AWS Lambda resource-based policy permissions.
499///
500/// # Recommended Usage
501/// Use the `lambda_permission_action!` macro from `rusty-cdk-macros` for compile-time validation
502#[derive(Debug, Clone)]
503pub struct LambdaPermissionAction(pub String);
504
505/// Name for AWS AppConfig applications, environments, or configuration profiles.
506///
507/// # Recommended Usage
508/// Use the `app_config_name!` macro from `rusty-cdk-macros` for compile-time validation
509#[derive(Debug, Clone)]
510pub struct AppConfigName(pub String);
511
512/// Deployment duration for AWS AppConfig deployments, specified in minutes.
513///
514/// # Recommended Usage
515/// Use the `deployment_duration_in_minutes!` macro from `rusty-cdk-macros` for compile-time validation
516///
517#[derive(Debug, Clone)]
518pub struct DeploymentDurationInMinutes(pub u16);
519
520/// Growth factor percentage for AWS AppConfig deployment strategies.
521///
522/// This wrapper configures the percentage of targets to receive the configuration
523/// during each deployment interval. AppConfig uses this to gradually roll out changes.
524///
525/// # Recommended Usage
526/// Use the `growth_factor!` macro from `rusty-cdk-macros` for compile-time validation
527///
528#[derive(Debug, Clone)]
529pub struct GrowthFactor(pub u8);
530
531/// Number of days before S3 objects transition to a different storage class.
532///
533/// # Recommended Usage
534/// Use the `lifecycle_transition_in_days!` macro from `rusty-cdk-macros` for compile-time validation:
535///
536/// ```rust
537/// use rusty_cdk_core::wrappers::LifecycleTransitionInDays;
538/// use rusty_cdk_macros::lifecycle_transition_in_days;
539///
540/// let transition = lifecycle_transition_in_days!(90,"Glacier");
541///
542/// let ia_transition = lifecycle_transition_in_days!(31,"StandardIA");
543/// ```
544#[derive(Debug, Clone)]
545pub struct LifecycleTransitionInDays(pub u16);
546
547/// LocationUri of AppConfig
548///
549/// # Recommended Usage
550/// Use the `location_uri!` macro from `rusty-cdk-macros` for compile-time validation:
551///
552/// ```rust
553/// use rusty_cdk_core::wrappers::LocationUri;
554/// use rusty_cdk_macros::location_uri;
555///
556/// // hosted does not require an additional argument
557/// let hosted = location_uri!("hosted");
558///
559/// // but s3 does
560/// let s3 = location_uri!("s3","s3://some-bucket/object");
561/// ```
562#[derive(Debug, Clone)]
563pub struct LocationUri(pub String);
564
565/// Name of an AppSync Api
566///
567/// # Recommended Usage
568/// Use the `app_sync_api_name!` macro from `rusty-cdk-macros` for compile-time validation
569#[derive(Debug, Clone)]
570pub struct AppSyncApiName(pub String);
571
572/// ChannelNamespace name for AppSync
573///
574/// # Recommended Usage
575/// Use the `channel_namespace_name!` macro from `rusty-cdk-macros` for compile-time validation
576#[derive(Debug, Clone)]
577pub struct ChannelNamespaceName(pub String);
rusty_cdk_core/wrappers/mod.rs

rusty_cdk_core/wrappers/
mod.rs
