From 5b6a7c1d2e5923cc2b5ce2678bbd3e4890d6d4c3 Mon Sep 17 00:00:00 2001 From: monabot Date: Tue, 24 Sep 2024 07:55:34 +0000 Subject: [PATCH] feat(docs): update docs Updates the Wing docs. See details in [workflow run]. [Workflow Run]: https://github.com/winglang/docsite/actions/runs/11009442888 ------ *Automatically created via the "update-docs" workflow* Signed-off-by: monabot --- .../version-latest/05-language-reference.md | 1 + .../998-archived/01-compile-targets.md | 4 +- .../02-concepts/03-platforms.md | 338 +---------------- .../01-understanding-platforms.md | 345 ++++++++++++++++++ .../version-latest/04-winglibs/04-toc.md | 62 ++-- .../04-winglibs/13-winglib-dynamodb.md | 138 +++++++ .../email.md => 14-winglib-email.md} | 5 +- ...entbridge.md => 15-winglib-eventbridge.md} | 0 ...b-fifoqueue.md => 16-winglib-fifoqueue.md} | 0 ...winglib-github.md => 17-winglib-github.md} | 0 .../{17-winglib-jwt.md => 18-winglib-jwt.md} | 0 .../{18-winglib-k8s.md => 19-winglib-k8s.md} | 0 ...{19-winglib-lock.md => 20-winglib-lock.md} | 0 ...efanout.md => 21-winglib-messagefanout.md} | 0 ...nglib-momento.md => 22-winglib-momento.md} | 0 ...2-winglib-ngrok.md => 23-winglib-ngrok.md} | 0 ...winglib-openai.md => 24-winglib-openai.md} | 0 ...lib-postgres.md => 25-winglib-postgres.md} | 0 ...winglib-python.md => 26-winglib-python.md} | 0 ...6-winglib-react.md => 27-winglib-react.md} | 0 ...7-winglib-redis.md => 28-winglib-redis.md} | 0 ...b-sagemaker.md => 29-winglib-sagemaker.md} | 0 .../{29-winglib-ses.md => 30-winglib-ses.md} | 0 ...lib-simtools.md => 31-winglib-simtools.md} | 0 ...1-winglib-slack.md => 32-winglib-slack.md} | 0 .../{32-winglib-sns.md => 33-winglib-sns.md} | 0 .../{33-winglib-tf.md => 34-winglib-tf.md} | 0 ...{34-winglib-tsoa.md => 35-winglib-tsoa.md} | 0 ...{35-winglib-vite.md => 36-winglib-vite.md} | 0 ...websockets.md => 37-winglib-websockets.md} | 0 30 files changed, 519 insertions(+), 374 deletions(-) create mode 100644 versioned_docs/version-latest/03-platforms/01-understanding-platforms.md rename versioned_docs/version-latest/04-winglibs/{05-winglibs/email.md => 14-winglib-email.md} (99%) rename versioned_docs/version-latest/04-winglibs/{14-winglib-eventbridge.md => 15-winglib-eventbridge.md} (100%) rename versioned_docs/version-latest/04-winglibs/{15-winglib-fifoqueue.md => 16-winglib-fifoqueue.md} (100%) rename versioned_docs/version-latest/04-winglibs/{16-winglib-github.md => 17-winglib-github.md} (100%) rename versioned_docs/version-latest/04-winglibs/{17-winglib-jwt.md => 18-winglib-jwt.md} (100%) rename versioned_docs/version-latest/04-winglibs/{18-winglib-k8s.md => 19-winglib-k8s.md} (100%) rename versioned_docs/version-latest/04-winglibs/{19-winglib-lock.md => 20-winglib-lock.md} (100%) rename versioned_docs/version-latest/04-winglibs/{20-winglib-messagefanout.md => 21-winglib-messagefanout.md} (100%) rename versioned_docs/version-latest/04-winglibs/{21-winglib-momento.md => 22-winglib-momento.md} (100%) rename versioned_docs/version-latest/04-winglibs/{22-winglib-ngrok.md => 23-winglib-ngrok.md} (100%) rename versioned_docs/version-latest/04-winglibs/{23-winglib-openai.md => 24-winglib-openai.md} (100%) rename versioned_docs/version-latest/04-winglibs/{24-winglib-postgres.md => 25-winglib-postgres.md} (100%) rename versioned_docs/version-latest/04-winglibs/{25-winglib-python.md => 26-winglib-python.md} (100%) rename versioned_docs/version-latest/04-winglibs/{26-winglib-react.md => 27-winglib-react.md} (100%) rename versioned_docs/version-latest/04-winglibs/{27-winglib-redis.md => 28-winglib-redis.md} (100%) rename versioned_docs/version-latest/04-winglibs/{28-winglib-sagemaker.md => 29-winglib-sagemaker.md} (100%) rename versioned_docs/version-latest/04-winglibs/{29-winglib-ses.md => 30-winglib-ses.md} (100%) rename versioned_docs/version-latest/04-winglibs/{30-winglib-simtools.md => 31-winglib-simtools.md} (100%) rename versioned_docs/version-latest/04-winglibs/{31-winglib-slack.md => 32-winglib-slack.md} (100%) rename versioned_docs/version-latest/04-winglibs/{32-winglib-sns.md => 33-winglib-sns.md} (100%) rename versioned_docs/version-latest/04-winglibs/{33-winglib-tf.md => 34-winglib-tf.md} (100%) rename versioned_docs/version-latest/04-winglibs/{34-winglib-tsoa.md => 35-winglib-tsoa.md} (100%) rename versioned_docs/version-latest/04-winglibs/{35-winglib-vite.md => 36-winglib-vite.md} (100%) rename versioned_docs/version-latest/04-winglibs/{36-winglib-websockets.md => 37-winglib-websockets.md} (100%) diff --git a/api_versioned_docs/version-latest/05-language-reference.md b/api_versioned_docs/version-latest/05-language-reference.md index f3240ad48..f280f6fa6 100644 --- a/api_versioned_docs/version-latest/05-language-reference.md +++ b/api_versioned_docs/version-latest/05-language-reference.md @@ -593,6 +593,7 @@ the following properties (given an example intrinsic `@x`): | `@assert()` | checks a condition and _throws_ if evaluated to false | | `@filename` | absolute path of the source file | | `@dirname` | absolute path of the source file's directory | +| `@target` | a string identifying the current target platform | | `@app` | the root of the construct tree | | `@unsafeCast()` | cast a value into a different type | | `@nodeof()` | obtain the [tree node](/docs/concepts/application-tree) of a preflight object | diff --git a/contributing_versioned_docs/version-latest/998-archived/01-compile-targets.md b/contributing_versioned_docs/version-latest/998-archived/01-compile-targets.md index 8bac36088..9ce21c51f 100644 --- a/contributing_versioned_docs/version-latest/998-archived/01-compile-targets.md +++ b/contributing_versioned_docs/version-latest/998-archived/01-compile-targets.md @@ -74,7 +74,7 @@ new cloud.Function(inflight ()=> { // push a message to queue queue.push("m"); // sleep according to target - if util.env("WING_TARGET") == "sim" { + if @target == "sim" { log("Running on Simulator, sleeping for 1s"); util.sleep(1s); } else { @@ -85,7 +85,7 @@ new cloud.Function(inflight ()=> { }); ``` -In this example, we want to sleep briefly for the Simulator target and for 30 seconds for cloud targets, this is achieved using the `WING_TARGET` environment variable. +In this example, we want to sleep briefly for the simulator target and for 30 seconds for cloud targets, this is achieved using the `@target` intrinsic function. ## Compiler plugins diff --git a/versioned_docs/version-latest/02-concepts/03-platforms.md b/versioned_docs/version-latest/02-concepts/03-platforms.md index 652337e52..98d7ef3de 100644 --- a/versioned_docs/version-latest/02-concepts/03-platforms.md +++ b/versioned_docs/version-latest/02-concepts/03-platforms.md @@ -5,341 +5,5 @@ description: Wing platforms keywords: [platforms, targets, target, platform, aws, gcp, azure, sim, terraform, cloudformation, pulumi, provisioning engines, multi-cloud] --- -When working with the Wing programming language, an integral part of the compilation process is the use of platform. In essence, platform specify how and where your application is deployed. They determine both the cloud environment and the provisioning engine that the code will be deployed with. +TODO: High level summary of platforms? Linking to the platforms section we have? -You can view the list of available builtin platform with the `wing compile --help` command. Here is an example of the output: - -```sh -wing compile --help -Usage: wing compile [options] [entrypoint] - -Compiles a Wing program - -Arguments: - entrypoint program .w entrypoint - -Options: - -t, --platform --platform Target platform provider (builtin: sim, tf-aws, tf-azure, tf-gcp) (default: [sim]) - -h, --help display help for command -``` - -Wing is shipped with several builtin platforms such as `sim`, `tf-aws`, `tf-azure`, and `tf-gcp` but it is also possible to create and use [custom platforms](#custom-platforms) to fully control how Wing resources are deployed to the cloud. - -These providers contain a combination of provision engine and cloud environment in their names, we refer to these as the platform target (which is discussed in more detail below). The only exception is `sim`, which is a special platform for testing and simulating applications locally. - -### Specifying Multiple Platforms - -You may have noticed that the `--platform` option can be provided multiple times. This means you can specify multiple platforms to compile your application to. For example, if you wanted to compile your application using multiple platforms - -```sh -wing compile app.main.w --platform tf-aws --platform platform-foo --platform platform-bar -``` -The order in which platforms are evaluated is important. - -The first platform in the list is the primary platform, it is responsible for providing the Wing compiler with the base App that will be used to determine how resources are created, as well it will also lay the ground work for what target the rest of the platforms will need to be compatible with. - -#### Implicit Platforms - -Additionally, you can use naming conventions to implicitly define platforms that should be used. These platform files can be located in the root of your project or in a library that your project uses. The naming convention is as follows: -```sh -wplatform.js -*.wplatform.js -``` - -For example, if you have a file named `custom.wplatform.js` in the root of your project, it will automatically be added to the list of platforms to be used when compiling your application. Its also important to note that implicit platforms are always loaded after the platforms specified in the `--platform` option. - -The use of implicit platforms can be beneficial when writing a Wing library that requires a specific platform to be used. For example, if you are writing a library that requires a specific parameter to be passed to the platform, you can use an implicit platform to ensure that the parameter is always provided. - -For example, if your library structure looks like this: - -```sh -my-library/ - lib.w - custom.wplatform.js -``` - -Then the custom platform can define any required parameters that the library needs to function properly. (see [Defining Custom Platform Parameters](#defining-custom-platform-parameters) for more information on how to define custom platform parameters) - - -### Provisioning Engines - -Provisioning is the process of setting up and creating infrastructure, and the provisioning engine is the driver behind this deployment. Common engines used in the Wing compilation process include Terraform and AWS CDK, with support for more planned ([tracking issue](https://github.com/winglang/wing/issues/2066)). - -Understanding the differences between provisioning engines will help as we dive deeper into the additional concepts of the platform provider system. - -### Platform Targets - -Platform targets are the combination of a provisioning engine and a cloud environment. For example, `tf-aws` is a platform target that uses Terraform as the provisioning engine and AWS as the cloud environment. - -It is worth noting that the platform names are not guaranteed to match their targets, we will see this more as we delve into the idea of Custom Platforms below. - -Though not currently implemented, the platform target system is designed with extensibility in mind, as it will be used to determine compatibility between different platforms ([tracking issue](https://github.com/winglang/wing/issues/1474)) - -#### Platform Parameters - -Some platform targets may require additional parameters to be provided. These parameters can be used to pass configuration values to the platform. For example, the platform target `tf-aws` has an optional parameter that can be specified to determine if a new VPC -should be created or if an existing VPC should be used. In order to provide this parameter, you can use the `--value` option in the cli to specify a key-value pair. For example: - -```sh -wing compile app.main.w --platform tf-aws --value tf-aws/vpc=existing -``` - -which will tell the `tf-aws` platform to use an existing VPC. However this will result in an parameter validation error, since when using an existing VPC, you will be required to add additional parameters such as `vpcId` and subnets. As shown in the error below: - -```sh -Error: Parameter validation errors: -- must have required property 'vpc_id' -- must have required property 'private_subnet_ids' -- must have required property 'public_subnet_ids' -``` - -it is possible to provide these additional parameters using the `--value` option as well. For example: - -```sh -wing compile app.main.w --platform tf-aws --value tf-aws/vpc=existing --value tf-aws/vpcId=vpc-1234567890 --value tf-aws/privateSubnetId=subnet-1234567890 --value tf-aws/publicSubnetId=subnet-1234567890 -``` - -Though this may be a bit verbose. As an alternative you can use a values file. Value files are a way to provide multiple config values in a single file. By default the compiler will look for a file named `wing` with any of the following extensions `.json`, `.yaml`, `.yml`, `.toml` Though you can also specify a custom file using the `--values` option. - -Here is an example of using a `wing.toml` file to provide the same parameters as above: - -```toml -[ tf-aws ] -# vpc can be set to "new" or "existing" -vpc = "new" -# vpc_lambda will ensure that lambda functions are created within the vpc on the private subnet -vpc_lambda = true -# vpc_api_gateway will ensure that the api gateway is created within the vpc on the private subnet -vpc_api_gateway = true -# The following parameters will be required if using "existing" vpc -# vpc_id = "vpc-123xyz" -# private_subnet_ids = ["subnet-123xyz"] -# public_subnet_ids = ["subnet-123xyz"] -``` - -#### Target-specific code - -There might be times when you need to write code that is specific to a particular platform target. For example, you may want to activate a verbose logging service only when testing locally to save on cloud log storage costs. - -With the Wing `util` library, you can access environment variables. The `WING_TARGET` environment variable contains the current platform target as it's value, which you can use to conditionally run target-specific code. See the example below: - -```js playground example -bring cloud; -bring util; - -let invocationCounter = new cloud.Counter(); -let queue = new cloud.Queue(); - -queue.setConsumer(inflight (msg: str) => { - invocationCounter.inc(); -}); - -new cloud.Function(inflight ()=> { - // push a message to queue - queue.push("m"); - // sleep according to target - if util.env("WING_TARGET") == "sim" { - log("Running on Simulator, sleeping for 1s"); - util.sleep(1s); - } else { - log("Running on the cloud, sleeping for 30s"); - util.sleep(30s); - } - log("Function invoked {invocationCounter.peek()} times"); -}); - -``` - -## Custom Platforms - -Wing's platform architecture is not just limited to the built-in platforms that come with the language; it's extensible. This means you can create custom platforms tailored to your needs, whether to support a unique cloud provider, introduce additional optimization layers, or integrate with specific enterprise systems. - -### Why might you want to create a custom platform? - -There are many reasons why you might want to create a custom platform. Here are a few examples: - -- Custom infrastructure requirements: Wing's built-in platforms are opinionated about how various resources are implemented. With custom platforms, you can fully control the infrastructure configuration of each cloud resource based on the needs, policies and constraints of your team. - -- Enhanced Security: Some organizations have stringent security requirements. With custom platforms, you can embed additional security checks, audits, or encryption layers to suit these needs. - -- Optimizations: Your organization may have developed optimization strategies that can help reduce costs or improve performance when deploying applications. Integrating these strategies into a custom platform can make them a seamless part of the deployment process. - -### Creating a custom platform - -Developing a custom platform requires understanding and adhering to the `IPlatform` interface. This ensures that your custom platform can be integrated smoothly with the Wing compilation process. - -The IPlatform interface is defined as follows: - -```ts -export interface IPlatform { - // Define the target compatibility of the platform - readonly target: string; - - // Define the App that will be used for creating resources - newApp?(appProps: AppProps): App; - - // Define overrides for concrete resources - newInstance?(type: string, scope: Construct, id: string, props: any): any; - - // Synthesis Hooks - preSynth?(app: Construct): void; - postSynth?(config: any): any; - validate?(config: any): any; -} -``` - -### Using a custom platform - -When running the `wing compile` command, the `--platform` option is used to specify the platform provider(s) you wish to use. This option accepts variadic arguments, which means you can specify any number of platforms. - -The specified platform can be a built-in platform, or a path to a custom platform. For example, if you have a custom platform named `my-platform`, you can specify it as follows: - -```sh -wing compile --platform tf-aws --platform ../my-platform -``` - -### Synthesis Hooks - -In the above interface there are three methods that are categorized as synthesis hooks. These hooks are called by the compiler at various points during the compilation process. They allow you to hook into the compilation process and apply customizations. - -Your platform only needs to implement the methods that are relevant to your use case. For example, if you are creating a platform that is designed to apply additional security configurations for your organization, then you may only need to implement the `preSynth` hook. - -Lets take a look at what each hook is responsible for: - -:::info Examples Incoming -The following examples of hooks use simple JavaScript files for brevity. However, you can and probably would want to build your platform as a Node library to package and distribute it. Examples of this are coming soon. -::: - -### `preSynth` hook - -API Reference -```ts -preSynth(app: Construct): void; -``` - -This hook is called before the compiler begins to synthesize. In the context of a -Terraform-based platform like `tf-aws`, this hook will have access to the root -node of the construct tree. This allows the platform to add or change [CDK for -Terraform](https://github.com/hashicorp/terraform-cdk) constructs before the -tree is synthesized. - -The following example adds a bucket to the root node. -```js -const s3_bucket = require("@cdktf/provider-aws/lib/s3-bucket"); - -exports.Platform = class MyPlatform { - preSynth(app) { - // app is the root node of the construct tree - new s3_bucket.S3Bucket(app, "MyPlatformBucket", { - bucket: "my-platform-bucket", - }); - } -} -``` - -### `postSynth` hook - -API Reference -```ts -postSynth(config: any): any; -``` - -This hook runs after artifacts were synthesized. When compiling to a -Terraform-based platform like `tf-aws`, the hook will have access -to the raw Terraform JSON configuration, allowing for manipulation of the JSON -that is written to the compiled output directory. - -This hook is useful for adding customizations that can not be applied in the -context of the preSynth hook. Its worth noting that this is not meant as a -validation phase since the config is still mutable by subsequent platforms. - -The following example manipulates the Terraform configuration to use a S3 -backend. For brevity, the example uses hard coded values. -```js -exports.Platform = class MyPlatform { - postSynth(config) { - config.terraform.backend = { - s3: { - bucket: "my-wing-state-bucket", - key: "platforms-rock.tfstate", - region: "us-east-1", - } - } - return config; - } -} -``` - -### `validate` hook - -API Reference -```ts -validate(config: any): void; -``` - -This hook is called right after the `postSynth` hook and provided the same -context object. In the context of a Terraform-based platform like `tf-aws`, this -is the same Terraform JSON configuration. However, does not allow configuration -to be mutated, which allows platforms to validate the configuration without -worrying about another platform mutating after the fact. - -The following example validates that buckets all have versioning enabled -and throw an error during compilation if they don't. -```js -exports.Platform = class MyPlatform { - validate(config) { - for (const bucketEntry of Object.keys(config.resource.aws_s3_bucket)) { - const bucket = config.resource.aws_s3_bucket[bucketEntry]; - if (!bucket.versioning.enabled) { - throw new Error(`Bucket ${bucketEntry} does not have versioning enabled`); - } - } - } -} -``` - -### Defining Custom Platform Parameters - -In addition to the hooks mentioned above, you can also define custom parameters for your platform. These parameters can be used to pass -configuration to your platform and can be optional or required. - -Parameters are defined using the `parameters` property of the platform. These parameters are expected to be provided in the form of a -(JSON schema)[https://json-schema.org/]. - -The following example shoes how to define three parameters `replicateAllBuckets`, `bucketsToReplicate` and `replicaRegion` for a custom platform. -Our platform's logic will either replicate all buckets if `replicateAllBuckets` is set to `true` or replicate only the buckets specified in `bucketsToReplicate` to the region specified in `replicaRegion`. - -Its important to understand the relationship between these parameters, as in if `replicateAllBuckets` is set to `true` then `bucketsToReplicate` is not required. -Whereas no matter the value of `replicateAllBuckets`, `replicaRegion` is always required. - -Luckily, JSON schema allows us to define these relationships and constraints like so: - -```js -class MyPlatform { - parameters = { - type: "object", - required: ["replicateAllBuckets", "replicaRegion"], - properties: { - replicateAllBuckets: { - type: "boolean", - }, - nameOfBucketsToReplicate: { - type: "array", - items: { - type: "string", - }, - }, - replicaRegion: { - type: "string", - }, - }, - "$comment": "Here in an allOf we can define multiple conditions that must be met for the schema to be valid", - allOf: [ - { - if: { properties: { replicateAllBuckets: { const: false }} }, - then: { required: ["nameOfBucketsToReplicate"] }, - } - ] - } -} -``` \ No newline at end of file diff --git a/versioned_docs/version-latest/03-platforms/01-understanding-platforms.md b/versioned_docs/version-latest/03-platforms/01-understanding-platforms.md new file mode 100644 index 000000000..a8ae86382 --- /dev/null +++ b/versioned_docs/version-latest/03-platforms/01-understanding-platforms.md @@ -0,0 +1,345 @@ +--- +title: What are platforms? +id: platforms +description: Wing platforms +keywords: [platforms, targets, target, platform, aws, gcp, azure, sim, terraform, cloudformation, pulumi, provisioning engines, multi-cloud] +--- + +When working with the Wing programming language, an integral part of the compilation process is the use of platform. In essence, platform specify how and where your application is deployed. They determine both the cloud environment and the provisioning engine that the code will be deployed with. + +You can view the list of available builtin platform with the `wing compile --help` command. Here is an example of the output: + +```sh +wing compile --help +Usage: wing compile [options] [entrypoint] + +Compiles a Wing program + +Arguments: + entrypoint program .w entrypoint + +Options: + -t, --platform --platform Target platform provider (builtin: sim, tf-aws, tf-azure, tf-gcp) (default: [sim]) + -h, --help display help for command +``` + +Wing is shipped with several builtin platforms such as `sim`, `tf-aws`, `tf-azure`, and `tf-gcp` but it is also possible to create and use [custom platforms](#custom-platforms) to fully control how Wing resources are deployed to the cloud. + +These providers contain a combination of provision engine and cloud environment in their names, we refer to these as the platform target (which is discussed in more detail below). The only exception is `sim`, which is a special platform for testing and simulating applications locally. + +### Specifying Multiple Platforms + +You may have noticed that the `--platform` option can be provided multiple times. This means you can specify multiple platforms to compile your application to. For example, if you wanted to compile your application using multiple platforms + +```sh +wing compile app.main.w --platform tf-aws --platform platform-foo --platform platform-bar +``` +The order in which platforms are evaluated is important. + +The first platform in the list is the primary platform, it is responsible for providing the Wing compiler with the base App that will be used to determine how resources are created, as well it will also lay the ground work for what target the rest of the platforms will need to be compatible with. + +#### Implicit Platforms + +Additionally, you can use naming conventions to implicitly define platforms that should be used. These platform files can be located in the root of your project or in a library that your project uses. The naming convention is as follows: +```sh +wplatform.js +*.wplatform.js +``` + +For example, if you have a file named `custom.wplatform.js` in the root of your project, it will automatically be added to the list of platforms to be used when compiling your application. Its also important to note that implicit platforms are always loaded after the platforms specified in the `--platform` option. + +The use of implicit platforms can be beneficial when writing a Wing library that requires a specific platform to be used. For example, if you are writing a library that requires a specific parameter to be passed to the platform, you can use an implicit platform to ensure that the parameter is always provided. + +For example, if your library structure looks like this: + +```sh +my-library/ + lib.w + custom.wplatform.js +``` + +Then the custom platform can define any required parameters that the library needs to function properly. (see [Defining Custom Platform Parameters](#defining-custom-platform-parameters) for more information on how to define custom platform parameters) + + +### Provisioning Engines + +Provisioning is the process of setting up and creating infrastructure, and the provisioning engine is the driver behind this deployment. Common engines used in the Wing compilation process include Terraform and AWS CDK, with support for more planned ([tracking issue](https://github.com/winglang/wing/issues/2066)). + +Understanding the differences between provisioning engines will help as we dive deeper into the additional concepts of the platform provider system. + +### Platform Targets + +Platform targets are the combination of a provisioning engine and a cloud environment. For example, `tf-aws` is a platform target that uses Terraform as the provisioning engine and AWS as the cloud environment. + +It is worth noting that the platform names are not guaranteed to match their targets, we will see this more as we delve into the idea of Custom Platforms below. + +Though not currently implemented, the platform target system is designed with extensibility in mind, as it will be used to determine compatibility between different platforms ([tracking issue](https://github.com/winglang/wing/issues/1474)) + +#### Platform Parameters + +Some platform targets may require additional parameters to be provided. These parameters can be used to pass configuration values to the platform. For example, the platform target `tf-aws` has an optional parameter that can be specified to determine if a new VPC +should be created or if an existing VPC should be used. In order to provide this parameter, you can use the `--value` option in the cli to specify a key-value pair. For example: + +```sh +wing compile app.main.w --platform tf-aws --value tf-aws/vpc=existing +``` + +which will tell the `tf-aws` platform to use an existing VPC. However this will result in an parameter validation error, since when using an existing VPC, you will be required to add additional parameters such as `vpcId` and subnets. As shown in the error below: + +```sh +Error: Parameter validation errors: +- must have required property 'vpc_id' +- must have required property 'private_subnet_ids' +- must have required property 'public_subnet_ids' +``` + +it is possible to provide these additional parameters using the `--value` option as well. For example: + +```sh +wing compile app.main.w --platform tf-aws --value tf-aws/vpc=existing --value tf-aws/vpcId=vpc-1234567890 --value tf-aws/privateSubnetId=subnet-1234567890 --value tf-aws/publicSubnetId=subnet-1234567890 +``` + +Though this may be a bit verbose. As an alternative you can use a values file. Value files are a way to provide multiple config values in a single file. By default the compiler will look for a file named `wing` with any of the following extensions `.json`, `.yaml`, `.yml`, `.toml` Though you can also specify a custom file using the `--values` option. + +Here is an example of using a `wing.toml` file to provide the same parameters as above: + +```toml +[ tf-aws ] +# vpc can be set to "new" or "existing" +vpc = "new" +# vpc_lambda will ensure that lambda functions are created within the vpc on the private subnet +vpc_lambda = true +# vpc_api_gateway will ensure that the api gateway is created within the vpc on the private subnet +vpc_api_gateway = true +# The following parameters will be required if using "existing" vpc +# vpc_id = "vpc-123xyz" +# private_subnet_ids = ["subnet-123xyz"] +# public_subnet_ids = ["subnet-123xyz"] +``` + +#### Target-specific code + +There might be times when you need to write code that is specific to a particular platform target. For example, you may want to activate a verbose logging service only when testing locally to save on cloud log storage costs. + +The `@target` intrinsic returns the current platform target as a string value, which you can use to conditionally run target-specific code. See the example below: + +```js playground example +bring cloud; +bring util; + +let invocationCounter = new cloud.Counter(); +let queue = new cloud.Queue(); + +queue.setConsumer(inflight (msg: str) => { + invocationCounter.inc(); +}); + +new cloud.Function(inflight ()=> { + // push a message to queue + queue.push("m"); + // sleep according to target + if @target == "sim" { + log("Running on Simulator, sleeping for 1s"); + util.sleep(1s); + } else { + log("Running on the cloud, sleeping for 30s"); + util.sleep(30s); + } + log("Function invoked {invocationCounter.peek()} times"); +}); + +``` + +## Custom Platforms + +Wing's platform architecture is not just limited to the built-in platforms that come with the language; it's extensible. This means you can create custom platforms tailored to your needs, whether to support a unique cloud provider, introduce additional optimization layers, or integrate with specific enterprise systems. + +### Why might you want to create a custom platform? + +There are many reasons why you might want to create a custom platform. Here are a few examples: + +- Custom infrastructure requirements: Wing's built-in platforms are opinionated about how various resources are implemented. With custom platforms, you can fully control the infrastructure configuration of each cloud resource based on the needs, policies and constraints of your team. + +- Enhanced Security: Some organizations have stringent security requirements. With custom platforms, you can embed additional security checks, audits, or encryption layers to suit these needs. + +- Optimizations: Your organization may have developed optimization strategies that can help reduce costs or improve performance when deploying applications. Integrating these strategies into a custom platform can make them a seamless part of the deployment process. + +### Creating a custom platform + +Developing a custom platform requires understanding and adhering to the `IPlatform` interface. This ensures that your custom platform can be integrated smoothly with the Wing compilation process. + +The IPlatform interface is defined as follows: + +```ts +export interface IPlatform { + // Define the target compatibility of the platform + readonly target: string; + + // Define the App that will be used for creating resources + newApp?(appProps: AppProps): App; + + // Define overrides for concrete resources + newInstance?(type: string, scope: Construct, id: string, props: any): any; + + // Synthesis Hooks + preSynth?(app: Construct): void; + postSynth?(config: any): any; + validate?(config: any): any; +} +``` + +### Using a custom platform + +When running the `wing compile` command, the `--platform` option is used to specify the platform provider(s) you wish to use. This option accepts variadic arguments, which means you can specify any number of platforms. + +The specified platform can be a built-in platform, or a path to a custom platform. For example, if you have a custom platform named `my-platform`, you can specify it as follows: + +```sh +wing compile --platform tf-aws --platform ../my-platform +``` + +### Synthesis Hooks + +In the above interface there are three methods that are categorized as synthesis hooks. These hooks are called by the compiler at various points during the compilation process. They allow you to hook into the compilation process and apply customizations. + +Your platform only needs to implement the methods that are relevant to your use case. For example, if you are creating a platform that is designed to apply additional security configurations for your organization, then you may only need to implement the `preSynth` hook. + +Lets take a look at what each hook is responsible for: + +:::info Examples Incoming +The following examples of hooks use simple JavaScript files for brevity. However, you can and probably would want to build your platform as a Node library to package and distribute it. Examples of this are coming soon. +::: + +### `preSynth` hook + +API Reference +```ts +preSynth(app: Construct): void; +``` + +This hook is called before the compiler begins to synthesize. In the context of a +Terraform-based platform like `tf-aws`, this hook will have access to the root +node of the construct tree. This allows the platform to add or change [CDK for +Terraform](https://github.com/hashicorp/terraform-cdk) constructs before the +tree is synthesized. + +The following example adds a bucket to the root node. +```js +const s3_bucket = require("@cdktf/provider-aws/lib/s3-bucket"); + +exports.Platform = class MyPlatform { + preSynth(app) { + // app is the root node of the construct tree + new s3_bucket.S3Bucket(app, "MyPlatformBucket", { + bucket: "my-platform-bucket", + }); + } +} +``` + +### `postSynth` hook + +API Reference +```ts +postSynth(config: any): any; +``` + +This hook runs after artifacts were synthesized. When compiling to a +Terraform-based platform like `tf-aws`, the hook will have access +to the raw Terraform JSON configuration, allowing for manipulation of the JSON +that is written to the compiled output directory. + +This hook is useful for adding customizations that can not be applied in the +context of the preSynth hook. Its worth noting that this is not meant as a +validation phase since the config is still mutable by subsequent platforms. + +The following example manipulates the Terraform configuration to use a S3 +backend. For brevity, the example uses hard coded values. +```js +exports.Platform = class MyPlatform { + postSynth(config) { + config.terraform.backend = { + s3: { + bucket: "my-wing-state-bucket", + key: "platforms-rock.tfstate", + region: "us-east-1", + } + } + return config; + } +} +``` + +### `validate` hook + +API Reference +```ts +validate(config: any): void; +``` + +This hook is called right after the `postSynth` hook and provided the same +context object. In the context of a Terraform-based platform like `tf-aws`, this +is the same Terraform JSON configuration. However, does not allow configuration +to be mutated, which allows platforms to validate the configuration without +worrying about another platform mutating after the fact. + +The following example validates that buckets all have versioning enabled +and throw an error during compilation if they don't. +```js +exports.Platform = class MyPlatform { + validate(config) { + for (const bucketEntry of Object.keys(config.resource.aws_s3_bucket)) { + const bucket = config.resource.aws_s3_bucket[bucketEntry]; + if (!bucket.versioning.enabled) { + throw new Error(`Bucket ${bucketEntry} does not have versioning enabled`); + } + } + } +} +``` + +### Defining Custom Platform Parameters + +In addition to the hooks mentioned above, you can also define custom parameters for your platform. These parameters can be used to pass +configuration to your platform and can be optional or required. + +Parameters are defined using the `parameters` property of the platform. These parameters are expected to be provided in the form of a +(JSON schema)[https://json-schema.org/]. + +The following example shoes how to define three parameters `replicateAllBuckets`, `bucketsToReplicate` and `replicaRegion` for a custom platform. +Our platform's logic will either replicate all buckets if `replicateAllBuckets` is set to `true` or replicate only the buckets specified in `bucketsToReplicate` to the region specified in `replicaRegion`. + +Its important to understand the relationship between these parameters, as in if `replicateAllBuckets` is set to `true` then `bucketsToReplicate` is not required. +Whereas no matter the value of `replicateAllBuckets`, `replicaRegion` is always required. + +Luckily, JSON schema allows us to define these relationships and constraints like so: + +```js +class MyPlatform { + parameters = { + type: "object", + required: ["replicateAllBuckets", "replicaRegion"], + properties: { + replicateAllBuckets: { + type: "boolean", + }, + nameOfBucketsToReplicate: { + type: "array", + items: { + type: "string", + }, + }, + replicaRegion: { + type: "string", + }, + }, + "$comment": "Here in an allOf we can define multiple conditions that must be met for the schema to be valid", + allOf: [ + { + if: { properties: { replicateAllBuckets: { const: false }} }, + then: { required: ["nameOfBucketsToReplicate"] }, + } + ] + } +} +``` diff --git a/versioned_docs/version-latest/04-winglibs/04-toc.md b/versioned_docs/version-latest/04-winglibs/04-toc.md index 74a3404f6..fce8d3434 100644 --- a/versioned_docs/version-latest/04-winglibs/04-toc.md +++ b/versioned_docs/version-latest/04-winglibs/04-toc.md @@ -8,37 +8,37 @@ keywords: [winglib, Wing library] | Library | Package name | Version | Description | Supported Wing platforms | | -------- | ------- | ------- | ------- | ------- | -| [Amazon Bedrock](/docs/winglibs/winglibs/bedrock) | [@winglibs/bedrock](/docs/winglibs/winglibs/bedrock) | v0.1.2 | A Wing library for Amazon Bedrock | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [AWS Budget](/docs/winglibs/winglibs/budget) | [@winglibs/budget](/docs/winglibs/winglibs/budget) | v0.1.7 | A Wing library for working with [AWS Budgets] | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Cloud checks](/docs/winglibs/winglibs/checks) | [@winglibs/checks](/docs/winglibs/winglibs/checks) | v0.0.18 | A self-validation mechanism for cloud applications | [*](/docs/platforms/platforms) | -| [cloudv2](/docs/winglibs/winglibs/cloudv2) | [@winglibs/cloudv2](/docs/winglibs/winglibs/cloudv2) | v0.1.2 | Standard cloud library for Wing | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Amazon Cognito](/docs/winglibs/winglibs/cognito) | [@winglibs/cognito](/docs/winglibs/winglibs/cognito) | v0.0.14 | A wing library to work with Amazon Cognito | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Containers](/docs/winglibs/winglibs/containers) | [@winglibs/containers](/docs/winglibs/winglibs/containers) | v0.1.6 | Deploy containers with Wing | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Amazon DynamoDB](/docs/winglibs/winglibs/dynamodb) | [@winglibs/dynamodb](/docs/winglibs/winglibs/dynamodb) | v0.2.4 | A Wing library for Amazon DynamoDB | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Email](/docs/winglibs/winglibs/email) | [@winglibs/email](/docs/winglibs/winglibs/email) | v0.0.1 | A wing library for sending emails | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Amazon EventBridge](/docs/winglibs/winglibs/eventbridge) | [@winglibs/eventbridge](/docs/winglibs/winglibs/eventbridge) | v0.1.8 | A Wing library for working with Amazon EventBridge | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws), [awscdk](/docs/platforms/AWS/awscdk) | -| [FIFO Queue](/docs/winglibs/winglibs/fifoqueue) | [@winglibs/fifoqueue](/docs/winglibs/winglibs/fifoqueue) | v0.0.12 | A wing library to work with FIFO (first-in first-out) Queues | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [GitHub](/docs/winglibs/winglibs/github) | [@winglibs/github](/docs/winglibs/winglibs/github) | v0.0.16 | A wing library to work with GitHub Probot | [*](/docs/platforms/platforms) | -| [JWT authentication](/docs/winglibs/winglibs/jwt) | [@winglibs/jwt](/docs/winglibs/winglibs/jwt) | v0.0.9 | Wing library for JWT authentication | [*](/docs/platforms/platforms) | -| [Kubernetes (k8s)](/docs/winglibs/winglibs/k8s) | [@winglibs/k8s](/docs/winglibs/winglibs/k8s) | v0.0.10 | Wing for Kubernetes | k8s | -| [Lock](/docs/winglibs/winglibs/lock) | [@winglibs/lock](/docs/winglibs/winglibs/lock) | v0.0.8 | Wing library for cloud lock | [*](/docs/platforms/platforms) | -| [Message Fanout](/docs/winglibs/winglibs/messagefanout) | [@winglibs/messagefanout](/docs/winglibs/winglibs/messagefanout) | v0.0.9 | Wing library to fan out messages | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Momento](/docs/winglibs/winglibs/momento) | [@winglibs/momento](/docs/winglibs/winglibs/momento) | v0.0.6 | Wing library for [momento](https://www.gomomento.com/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws), [tf-gcp](/docs/platforms/google-cloud/tf-gcp), [tf-azure](/docs/platforms/microsoft-azure/tf-azure) | -| [ngrok](/docs/winglibs/winglibs/ngrok) | [@winglibs/ngrok](/docs/winglibs/winglibs/ngrok) | v0.0.11 | Wing library for [ngrok](https://ngrok.com/). Create local tunnels to Wing endpoints. | [*](/docs/platforms/platforms) | -| [OpenAI](/docs/winglibs/winglibs/openai) | [@winglibs/openai](/docs/winglibs/winglibs/openai) | v0.0.9 | Wing library for [OpenAI](https://openai.com/) | [*](/docs/platforms/platforms) | -| [Postgres](/docs/winglibs/winglibs/postgres) | [@winglibs/postgres](/docs/winglibs/winglibs/postgres) | v0.1.13 | Wing library for [Postgres](https://www.postgresql.org/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Python](/docs/winglibs/winglibs/python) | [@winglibs/python](/docs/winglibs/winglibs/python) | v0.1.4 | A Wing library for running [Python](https://www.python.org/) code in [inflight](https://www.winglang.io/docs/concepts/inflights#inflight-code). | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [React](/docs/winglibs/winglibs/react) | [@winglibs/react](/docs/winglibs/winglibs/react) | v0.1.6 | A Wing library for [React](https://react.dev/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Redis](/docs/winglibs/winglibs/redis) | [@winglibs/redis](/docs/winglibs/winglibs/redis) | v0.0.13 | A Wing library for [Redis](https://redis.io/) ([Example](https://www.winglang.io/docs/examples/redis)) | [sim](/docs/platforms/sim) | -| [Amazon SageMaker](/docs/winglibs/winglibs/sagemaker) | [@winglibs/sagemaker](/docs/winglibs/winglibs/sagemaker) | v0.0.10 | The library enables owners of a trained sagemaker model, to access its Endpoints from a winglang [inflight](https://www.winglang.io/docs/concepts/inflights#inflight-code) code. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Amazon SES](/docs/winglibs/winglibs/ses) | [@winglibs/ses](/docs/winglibs/winglibs/ses) | v0.0.8 | Wing library for interacting with Amazon SES. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Wing simulator utils](/docs/winglibs/winglibs/simtools) | [@winglibs/simtools](/docs/winglibs/winglibs/simtools) | v0.0.6 | '[Wing simulator](https://www.winglang.io/docs/platforms/sim) utility library' | [sim](/docs/platforms/sim) | -| [Slack](/docs/winglibs/winglibs/slack) | [@winglibs/slack](/docs/winglibs/winglibs/slack) | v0.1.5 | A Wing library for working with [Slack](https://slack.com/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [Amazon SNS](/docs/winglibs/winglibs/sns) | [@winglibs/sns](/docs/winglibs/winglibs/sns) | v0.1.7 | A Wing library for working with [Amazon SNS](https://aws.amazon.com/sns/) | [tf-aws](/docs/platforms/AWS/tf-aws), [awscdk](/docs/platforms/AWS/awscdk), [sim](/docs/platforms/sim) | -| [Terraform utilities](/docs/winglibs/winglibs/tf) | [@winglibs/tf](/docs/winglibs/winglibs/tf) | v0.1.0 | Terraform utilities library for Wing | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [tsoa](/docs/winglibs/winglibs/tsoa) | [@winglibs/tsoa](/docs/winglibs/winglibs/tsoa) | v0.1.16 | A Wing library for working with [TSOA](https://tsoa-community.github.io/docs/) - An OpenAPI-compliant Web APIs using TypeScript. | [sim](/docs/platforms/sim) | -| [Vite](/docs/winglibs/winglibs/vite) | [@winglibs/vite](/docs/winglibs/winglibs/vite) | v0.2.5 | A Wing library to deploy [Vite applications](https://vitejs.dev/) to the cloud. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | -| [WebSocket](/docs/winglibs/winglibs/websockets) | [@winglibs/websockets](/docs/winglibs/winglibs/websockets) | v0.3.13 | A Wing library that enables you to create WebSockets using Wing. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws), [awscdk](/docs/platforms/AWS/awscdk) | +| [Amazon Bedrock](/docs/winglibs/bedrock) | [@winglibs/bedrock](/docs/winglibs/bedrock) | v0.1.2 | A Wing library for Amazon Bedrock | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [AWS Budget](/docs/winglibs/budget) | [@winglibs/budget](/docs/winglibs/budget) | v0.1.7 | A Wing library for working with [AWS Budgets] | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Cloud checks](/docs/winglibs/checks) | [@winglibs/checks](/docs/winglibs/checks) | v0.0.18 | A self-validation mechanism for cloud applications | [*](/docs/platforms/platforms) | +| [cloudv2](/docs/winglibs/cloudv2) | [@winglibs/cloudv2](/docs/winglibs/cloudv2) | v0.1.2 | Standard cloud library for Wing | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Amazon Cognito](/docs/winglibs/cognito) | [@winglibs/cognito](/docs/winglibs/cognito) | v0.0.14 | A wing library to work with Amazon Cognito | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Containers](/docs/winglibs/containers) | [@winglibs/containers](/docs/winglibs/containers) | v0.1.6 | Deploy containers with Wing | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Amazon DynamoDB](/docs/winglibs/dynamodb) | [@winglibs/dynamodb](/docs/winglibs/dynamodb) | v0.3.0 | A Wing library for Amazon DynamoDB | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Email](/docs/winglibs/email) | [@winglibs/email](/docs/winglibs/email) | v0.0.1 | A wing library for sending emails | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Amazon EventBridge](/docs/winglibs/eventbridge) | [@winglibs/eventbridge](/docs/winglibs/eventbridge) | v0.1.8 | A Wing library for working with Amazon EventBridge | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws), [awscdk](/docs/platforms/AWS/awscdk) | +| [FIFO Queue](/docs/winglibs/fifoqueue) | [@winglibs/fifoqueue](/docs/winglibs/fifoqueue) | v0.0.12 | A wing library to work with FIFO (first-in first-out) Queues | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [GitHub](/docs/winglibs/github) | [@winglibs/github](/docs/winglibs/github) | v0.0.16 | A wing library to work with GitHub Probot | [*](/docs/platforms/platforms) | +| [JWT authentication](/docs/winglibs/jwt) | [@winglibs/jwt](/docs/winglibs/jwt) | v0.0.9 | Wing library for JWT authentication | [*](/docs/platforms/platforms) | +| [Kubernetes (k8s)](/docs/winglibs/k8s) | [@winglibs/k8s](/docs/winglibs/k8s) | v0.0.10 | Wing for Kubernetes | k8s | +| [Lock](/docs/winglibs/lock) | [@winglibs/lock](/docs/winglibs/lock) | v0.0.8 | Wing library for cloud lock | [*](/docs/platforms/platforms) | +| [Message Fanout](/docs/winglibs/messagefanout) | [@winglibs/messagefanout](/docs/winglibs/messagefanout) | v0.0.9 | Wing library to fan out messages | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Momento](/docs/winglibs/momento) | [@winglibs/momento](/docs/winglibs/momento) | v0.0.6 | Wing library for [momento](https://www.gomomento.com/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws), [tf-gcp](/docs/platforms/google-cloud/tf-gcp), [tf-azure](/docs/platforms/microsoft-azure/tf-azure) | +| [ngrok](/docs/winglibs/ngrok) | [@winglibs/ngrok](/docs/winglibs/ngrok) | v0.0.11 | Wing library for [ngrok](https://ngrok.com/). Create local tunnels to Wing endpoints. | [*](/docs/platforms/platforms) | +| [OpenAI](/docs/winglibs/openai) | [@winglibs/openai](/docs/winglibs/openai) | v0.0.9 | Wing library for [OpenAI](https://openai.com/) | [*](/docs/platforms/platforms) | +| [Postgres](/docs/winglibs/postgres) | [@winglibs/postgres](/docs/winglibs/postgres) | v0.1.13 | Wing library for [Postgres](https://www.postgresql.org/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Python](/docs/winglibs/python) | [@winglibs/python](/docs/winglibs/python) | v0.1.4 | A Wing library for running [Python](https://www.python.org/) code in [inflight](https://www.winglang.io/docs/concepts/inflights#inflight-code). | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [React](/docs/winglibs/react) | [@winglibs/react](/docs/winglibs/react) | v0.1.6 | A Wing library for [React](https://react.dev/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Redis](/docs/winglibs/redis) | [@winglibs/redis](/docs/winglibs/redis) | v0.0.13 | A Wing library for [Redis](https://redis.io/) ([Example](https://www.winglang.io/docs/examples/redis)) | [sim](/docs/platforms/sim) | +| [Amazon SageMaker](/docs/winglibs/sagemaker) | [@winglibs/sagemaker](/docs/winglibs/sagemaker) | v0.0.10 | The library enables owners of a trained sagemaker model, to access its Endpoints from a winglang [inflight](https://www.winglang.io/docs/concepts/inflights#inflight-code) code. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Amazon SES](/docs/winglibs/ses) | [@winglibs/ses](/docs/winglibs/ses) | v0.0.8 | Wing library for interacting with Amazon SES. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Wing simulator utils](/docs/winglibs/simtools) | [@winglibs/simtools](/docs/winglibs/simtools) | v0.0.6 | '[Wing simulator](https://www.winglang.io/docs/platforms/sim) utility library' | [sim](/docs/platforms/sim) | +| [Slack](/docs/winglibs/slack) | [@winglibs/slack](/docs/winglibs/slack) | v0.1.5 | A Wing library for working with [Slack](https://slack.com/) | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [Amazon SNS](/docs/winglibs/sns) | [@winglibs/sns](/docs/winglibs/sns) | v0.1.7 | A Wing library for working with [Amazon SNS](https://aws.amazon.com/sns/) | [tf-aws](/docs/platforms/AWS/tf-aws), [awscdk](/docs/platforms/AWS/awscdk), [sim](/docs/platforms/sim) | +| [Terraform utilities](/docs/winglibs/tf) | [@winglibs/tf](/docs/winglibs/tf) | v0.1.0 | Terraform utilities library for Wing | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [tsoa](/docs/winglibs/tsoa) | [@winglibs/tsoa](/docs/winglibs/tsoa) | v0.1.16 | A Wing library for working with [TSOA](https://tsoa-community.github.io/docs/) - An OpenAPI-compliant Web APIs using TypeScript. | [sim](/docs/platforms/sim) | +| [Vite](/docs/winglibs/vite) | [@winglibs/vite](/docs/winglibs/vite) | v0.2.5 | A Wing library to deploy [Vite applications](https://vitejs.dev/) to the cloud. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws) | +| [WebSocket](/docs/winglibs/websockets) | [@winglibs/websockets](/docs/winglibs/websockets) | v0.3.13 | A Wing library that enables you to create WebSockets using Wing. | [sim](/docs/platforms/sim), [tf-aws](/docs/platforms/AWS/tf-aws), [awscdk](/docs/platforms/AWS/awscdk) | ## Contributing to winglibs diff --git a/versioned_docs/version-latest/04-winglibs/13-winglib-dynamodb.md b/versioned_docs/version-latest/04-winglibs/13-winglib-dynamodb.md index 0508ef0d6..f05d4b4b6 100644 --- a/versioned_docs/version-latest/04-winglibs/13-winglib-dynamodb.md +++ b/versioned_docs/version-latest/04-winglibs/13-winglib-dynamodb.md @@ -84,19 +84,26 @@ This library is licensed under the [MIT License](./LICENSE). - Client - **Interfaces** - IClient + - IDynamoResource - ITable - **Structs** - AttributeDefinition + - BatchGetOptions + - BatchGetOutput + - BatchWriteOptions + - BatchWriteOutput - ClientConfig - Connection - Credentials - DeleteOptions - DeleteOutput + - DeleteRequest - GetOptions - GetOutput - GlobalSecondaryIndex - PutOptions - PutOutput + - PutRequest - QueryOptions - QueryOutput - ScanOptions @@ -104,6 +111,8 @@ This library is licensed under the [MIT License](./LICENSE). - StreamConsumerOptions - StreamRecord - StreamRecordDynamodb + - TableBatchGetOptions + - TableBatchWriteOptions - TableProps - TransactWriteItem - TransactWriteItemConditionCheck @@ -139,6 +148,8 @@ new(props: TableProps): Table | **Signature** | **Description** | | --- | --- | +| inflight batchGet(options: TableBatchGetOptions): BatchGetOutput | *No description* | +| inflight batchWrite(options: TableBatchWriteOptions): BatchWriteOutput | *No description* | | inflight delete(options: DeleteOptions): DeleteOutput | *No description* | | inflight get(options: GetOptions): GetOutput | *No description* | | inflight put(options: PutOptions): PutOutput | *No description* | @@ -170,6 +181,8 @@ new(props: TableProps): Table_tfaws | **Signature** | **Description** | | --- | --- | +| inflight batchGet(options: TableBatchGetOptions): BatchGetOutput | *No description* | +| inflight batchWrite(options: TableBatchWriteOptions): BatchWriteOutput | *No description* | | inflight delete(options: DeleteOptions): DeleteOutput | *No description* | | inflight get(options: GetOptions): GetOutput | *No description* | | inflight put(options: PutOptions): PutOutput | *No description* | @@ -201,6 +214,8 @@ new(props: TableProps): Table_sim | **Signature** | **Description** | | --- | --- | +| inflight batchGet(options: TableBatchGetOptions): BatchGetOutput | *No description* | +| inflight batchWrite(options: TableBatchWriteOptions): BatchWriteOutput | *No description* | | inflight delete(options: DeleteOptions): DeleteOutput | *No description* | | inflight get(options: GetOptions): GetOutput | *No description* | | inflight put(options: PutOptions): PutOutput | *No description* | @@ -229,6 +244,8 @@ new(): Client | **Signature** | **Description** | | --- | --- | +| inflight batchGet(options: BatchGetOptions): BatchGetOutput | *No description* | +| inflight batchWrite(options: BatchWriteOptions): BatchWriteOutput | *No description* | | inflight delete(options: DeleteOptions): DeleteOutput | *No description* | | inflight get(options: GetOptions): GetOutput | *No description* | | inflight put(options: PutOptions): PutOutput | *No description* | @@ -247,6 +264,28 @@ new(): Client #### Methods +| **Signature** | **Description** | +| --- | --- | +| inflight batchGet(options: BatchGetOptions): BatchGetOutput | *No description* | +| inflight batchWrite(options: BatchWriteOptions): BatchWriteOutput | *No description* | +| inflight delete(options: DeleteOptions): DeleteOutput | *No description* | +| inflight get(options: GetOptions): GetOutput | *No description* | +| inflight put(options: PutOptions): PutOutput | *No description* | +| inflight query(options: QueryOptions): QueryOutput | *No description* | +| inflight scan(options: ScanOptions?): ScanOutput | *No description* | +| inflight transactWrite(options: TransactWriteOptions): TransactWriteOutput | *No description* | +| inflight update(options: UpdateOptions): UpdateOutput | *No description* | + +### IDynamoResource (interface) + +*No description* + +#### Properties + +*No properties* + +#### Methods + | **Signature** | **Description** | | --- | --- | | inflight delete(options: DeleteOptions): DeleteOutput | *No description* | @@ -269,6 +308,8 @@ new(): Client | **Signature** | **Description** | | --- | --- | +| inflight batchGet(options: TableBatchGetOptions): BatchGetOutput | *No description* | +| inflight batchWrite(options: TableBatchWriteOptions): BatchWriteOutput | *No description* | | inflight delete(options: DeleteOptions): DeleteOutput | *No description* | | inflight get(options: GetOptions): GetOutput | *No description* | | inflight put(options: PutOptions): PutOutput | *No description* | @@ -290,6 +331,53 @@ new(): Client | name | str | *No description* | | type | str | *No description* | +### BatchGetOptions (struct) + +Input to the `batchGet` operation on a Client. + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| RequestItems | Map | *No description* | +| ReturnConsumedCapacity | str? | *No description* | + +### BatchGetOutput (struct) + +*No description* + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| ConsumedCapacity | Array? | *No description* | +| Responses | Map>? | *No description* | +| UnprocessedKeys | Map | *No description* | + +### BatchWriteOptions (struct) + +Input to the `batchWrite` operation on a Client. + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| RequestItems | Map | *No description* | +| ReturnConsumedCapacity | str? | *No description* | +| ReturnItemCollectionMetrics | str? | *No description* | + +### BatchWriteOutput (struct) + +*No description* + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| ConsumedCapacity | Array? | *No description* | +| ItemCollectionMetrics | Json? | *No description* | +| UnprocessedItems | Map? | *No description* | + ### ClientConfig (struct) *No description* @@ -348,6 +436,16 @@ new(): Client | --- | --- | --- | | Attributes | Json? | *No description* | +### DeleteRequest (struct) + +Represents a request to perform a `DeleteItem` operation on an item. + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| Key | Json | `Key` is a map of attribute name to attribute values, representing the primary key of the item to delete. All of the table's primary key attributes must be specified | + ### GetOptions (struct) *No description* @@ -412,6 +510,16 @@ new(): Client | --- | --- | --- | | Attributes | Json? | *No description* | +### PutRequest (struct) + +Represents a request to perform a `PutItem` operation on an item. + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| Item | Json | A map of attribute name to attribute values, representing the primary key of an item to be processed by PutItem. All of the table's primary key attributes must be specified, and their data types must match those of the table's key schema. If any attributes are present in the item that are part of an index key schema for the table, their types must match the index key schema. | + ### QueryOptions (struct) *No description* @@ -521,6 +629,36 @@ new(): Client | SizeBytes | num | *No description* | | StreamViewType | str | *No description* | +### TableBatchGetOptions (struct) + +`TableBatchGetOptions` is used as an input to the `batchGet` operation on a Table or Client +(through [`BatchGetOptions`](#@winglibs/dynamodb.BatchGetOptions)). + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| AttributesToGet | Array? | *No description* | +| ConsistentRead | bool? | *No description* | +| ExpressionAttributeNames | Map? | *No description* | +| Keys | Array | *No description* | +| ProjectionExpression | str? | *No description* | +| ReturnConsumedCapacity | str? | When passed in on a **Table** resource, `ReturnConsumedCapacity` will be hoisted to the top level inside of the request. When passed in on a **Client** resource (via [`BatchGetOptions`](#@winglibs/dynamodb.BatchGetOptions)), setting `ReturnConsumedCapacity` here has no effect, set it inside of the top-level instead. | + +### TableBatchWriteOptions (struct) + +`TableBatchWriteOptions` is used as an input to the `batchWrite` operation on a Table or Client +(through [`BatchWriteOptions`](#@winglibs/dynamodb.BatchWriteOptions)). + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| DeleteRequests | Array? | `DeleteRequests` contains a list of `DeleteItem` operations to perform on this table. | +| PutRequests | Array? | `PutRequests` contains a list of `PutItem` operations to perform on this table. | +| ReturnConsumedCapacity | str? | When passed in on a **Table** resource, `ReturnConsumedCapacity` will be hoisted to the top level inside of the request. When passed in on a **Client** resource (via [`BatchWriteOptions`](#@winglibs/dynamodb.BatchWriteOptions)), setting `ReturnConsumedCapacity` here has no effect, set it inside of the top-level instead. | +| ReturnItemCollectionMetrics | str? | When passed in on a **Table** resource, `ReturnItemCollectionMetrics` will be hoisted to the top level inside of the request. When passed in on a **Client** resource (via [`BatchWriteOptions`](#@winglibs/dynamodb.BatchWriteOptions)), setting `ReturnConsumedCapacity` here has no effect, set it inside of the top-level instead. | + ### TableProps (struct) *No description* diff --git a/versioned_docs/version-latest/04-winglibs/05-winglibs/email.md b/versioned_docs/version-latest/04-winglibs/14-winglib-email.md similarity index 99% rename from versioned_docs/version-latest/04-winglibs/05-winglibs/email.md rename to versioned_docs/version-latest/04-winglibs/14-winglib-email.md index 6129564ca..6d557b3a6 100644 --- a/versioned_docs/version-latest/04-winglibs/05-winglibs/email.md +++ b/versioned_docs/version-latest/04-winglibs/14-winglib-email.md @@ -1,12 +1,10 @@ --- title: Email id: email -sidebar_label: Email +sidebar_label: Email (winglib) description: A wing library for sending emails keywords: [winglib, Wing library] --- -# email - ## Prerequisites * [winglang](https://winglang.io). @@ -52,7 +50,6 @@ By default, new AWS accounts are in the sandbox mode. This means emails can only ## License This library is licensed under the [MIT License](./LICENSE). - --- ## API Reference diff --git a/versioned_docs/version-latest/04-winglibs/14-winglib-eventbridge.md b/versioned_docs/version-latest/04-winglibs/15-winglib-eventbridge.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/14-winglib-eventbridge.md rename to versioned_docs/version-latest/04-winglibs/15-winglib-eventbridge.md diff --git a/versioned_docs/version-latest/04-winglibs/15-winglib-fifoqueue.md b/versioned_docs/version-latest/04-winglibs/16-winglib-fifoqueue.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/15-winglib-fifoqueue.md rename to versioned_docs/version-latest/04-winglibs/16-winglib-fifoqueue.md diff --git a/versioned_docs/version-latest/04-winglibs/16-winglib-github.md b/versioned_docs/version-latest/04-winglibs/17-winglib-github.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/16-winglib-github.md rename to versioned_docs/version-latest/04-winglibs/17-winglib-github.md diff --git a/versioned_docs/version-latest/04-winglibs/17-winglib-jwt.md b/versioned_docs/version-latest/04-winglibs/18-winglib-jwt.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/17-winglib-jwt.md rename to versioned_docs/version-latest/04-winglibs/18-winglib-jwt.md diff --git a/versioned_docs/version-latest/04-winglibs/18-winglib-k8s.md b/versioned_docs/version-latest/04-winglibs/19-winglib-k8s.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/18-winglib-k8s.md rename to versioned_docs/version-latest/04-winglibs/19-winglib-k8s.md diff --git a/versioned_docs/version-latest/04-winglibs/19-winglib-lock.md b/versioned_docs/version-latest/04-winglibs/20-winglib-lock.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/19-winglib-lock.md rename to versioned_docs/version-latest/04-winglibs/20-winglib-lock.md diff --git a/versioned_docs/version-latest/04-winglibs/20-winglib-messagefanout.md b/versioned_docs/version-latest/04-winglibs/21-winglib-messagefanout.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/20-winglib-messagefanout.md rename to versioned_docs/version-latest/04-winglibs/21-winglib-messagefanout.md diff --git a/versioned_docs/version-latest/04-winglibs/21-winglib-momento.md b/versioned_docs/version-latest/04-winglibs/22-winglib-momento.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/21-winglib-momento.md rename to versioned_docs/version-latest/04-winglibs/22-winglib-momento.md diff --git a/versioned_docs/version-latest/04-winglibs/22-winglib-ngrok.md b/versioned_docs/version-latest/04-winglibs/23-winglib-ngrok.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/22-winglib-ngrok.md rename to versioned_docs/version-latest/04-winglibs/23-winglib-ngrok.md diff --git a/versioned_docs/version-latest/04-winglibs/23-winglib-openai.md b/versioned_docs/version-latest/04-winglibs/24-winglib-openai.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/23-winglib-openai.md rename to versioned_docs/version-latest/04-winglibs/24-winglib-openai.md diff --git a/versioned_docs/version-latest/04-winglibs/24-winglib-postgres.md b/versioned_docs/version-latest/04-winglibs/25-winglib-postgres.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/24-winglib-postgres.md rename to versioned_docs/version-latest/04-winglibs/25-winglib-postgres.md diff --git a/versioned_docs/version-latest/04-winglibs/25-winglib-python.md b/versioned_docs/version-latest/04-winglibs/26-winglib-python.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/25-winglib-python.md rename to versioned_docs/version-latest/04-winglibs/26-winglib-python.md diff --git a/versioned_docs/version-latest/04-winglibs/26-winglib-react.md b/versioned_docs/version-latest/04-winglibs/27-winglib-react.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/26-winglib-react.md rename to versioned_docs/version-latest/04-winglibs/27-winglib-react.md diff --git a/versioned_docs/version-latest/04-winglibs/27-winglib-redis.md b/versioned_docs/version-latest/04-winglibs/28-winglib-redis.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/27-winglib-redis.md rename to versioned_docs/version-latest/04-winglibs/28-winglib-redis.md diff --git a/versioned_docs/version-latest/04-winglibs/28-winglib-sagemaker.md b/versioned_docs/version-latest/04-winglibs/29-winglib-sagemaker.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/28-winglib-sagemaker.md rename to versioned_docs/version-latest/04-winglibs/29-winglib-sagemaker.md diff --git a/versioned_docs/version-latest/04-winglibs/29-winglib-ses.md b/versioned_docs/version-latest/04-winglibs/30-winglib-ses.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/29-winglib-ses.md rename to versioned_docs/version-latest/04-winglibs/30-winglib-ses.md diff --git a/versioned_docs/version-latest/04-winglibs/30-winglib-simtools.md b/versioned_docs/version-latest/04-winglibs/31-winglib-simtools.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/30-winglib-simtools.md rename to versioned_docs/version-latest/04-winglibs/31-winglib-simtools.md diff --git a/versioned_docs/version-latest/04-winglibs/31-winglib-slack.md b/versioned_docs/version-latest/04-winglibs/32-winglib-slack.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/31-winglib-slack.md rename to versioned_docs/version-latest/04-winglibs/32-winglib-slack.md diff --git a/versioned_docs/version-latest/04-winglibs/32-winglib-sns.md b/versioned_docs/version-latest/04-winglibs/33-winglib-sns.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/32-winglib-sns.md rename to versioned_docs/version-latest/04-winglibs/33-winglib-sns.md diff --git a/versioned_docs/version-latest/04-winglibs/33-winglib-tf.md b/versioned_docs/version-latest/04-winglibs/34-winglib-tf.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/33-winglib-tf.md rename to versioned_docs/version-latest/04-winglibs/34-winglib-tf.md diff --git a/versioned_docs/version-latest/04-winglibs/34-winglib-tsoa.md b/versioned_docs/version-latest/04-winglibs/35-winglib-tsoa.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/34-winglib-tsoa.md rename to versioned_docs/version-latest/04-winglibs/35-winglib-tsoa.md diff --git a/versioned_docs/version-latest/04-winglibs/35-winglib-vite.md b/versioned_docs/version-latest/04-winglibs/36-winglib-vite.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/35-winglib-vite.md rename to versioned_docs/version-latest/04-winglibs/36-winglib-vite.md diff --git a/versioned_docs/version-latest/04-winglibs/36-winglib-websockets.md b/versioned_docs/version-latest/04-winglibs/37-winglib-websockets.md similarity index 100% rename from versioned_docs/version-latest/04-winglibs/36-winglib-websockets.md rename to versioned_docs/version-latest/04-winglibs/37-winglib-websockets.md