Skip to content

Commit 8165bc6

Browse files
conico974conico974
authored
Docs for aws 3.4 (#51)
1 parent 4f91a0a commit 8165bc6

File tree

8 files changed

+276
-169
lines changed

8 files changed

+276
-169
lines changed

‎pages/aws/config/overrides/_meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@
77
"image_loader": "Image Loader",
88
"proxy_external_request": "External Request Proxy",
99
"origin_resolver": "Origin Resolver",
10-
"invoke_function": "Invoke Function for the warmer"
10+
"invoke_function": "Invoke Function for the warmer",
11+
"automatic_cdn_invalidation": "Automatic CDN Invalidation"
1112
}

‎pages/aws/config/overrides/automatic_cdn_invalidation.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import {Callout} from 'nextra/components'
2+
3+
Available since `@opennextjs/aws` 3.4.0
4+
5+
This override is used by OpenNext when routes have been On-Demand revalidated and the CDN needs to be updated. It is not called for ISR revalidation.
6+
It will be called for `revalidatePath`, `revalidateTag` and `res.revalidate()`.
7+
8+
If you want to better understand how to implement your own Automatic CDN Invalidation, the easiest way would be to take a look at the existing [included Automatic CDN Invalidation](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/cdnInvalidation)
9+
10+
## Included Automatic CDN Invalidation
11+
12+
### dummy
13+
14+
The Dummy AutomaticCDNInvalidation is a dummy implementation that will do nothing. It is the default implementation.
15+
16+
### cloudfront
17+
18+
<Callout type='warning'>
19+
Cloudfront invalidation can be very expensive. Manual CloudFront path invalidation incurs costs. According to the [AWS CloudFront pricing page](https://aws.amazon.com/cloudfront/pricing/):
20+
21+
> No additional charge for the first 1,000 paths requested for invalidation each month. Thereafter, $0.005 per path requested for invalidation.
22+
23+
This implementation will send an invalidation request for every route that needs to be invalidated (the request invalidates 2 paths, one for the route itself and one for the data route).
24+
25+
Tag cache invalidation could end up triggering thousands of invalidation requests.
26+
27+
Only use this implementation if you are aware of the costs and are willing to pay for it.
28+
</Callout>
29+
30+
The CloudFront Automatic CDN Invalidation will invalidate the cache of the CloudFront distribution.
31+
32+
##### Requirements
33+
34+
- You need to provide the `CLOUDFRONT_DISTRIBUTION_ID` environment variable to your server.

‎pages/aws/config/overrides/image_loader.mdx‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,32 @@ This override is used by OpenNext and more specifically by the image server to b
22

33
This is used for internal image only (i.e. src without host). External source are already handled by the image server.
44

5-
If you want to better understand how to implement your own ImageLoader, the easiest way would be to take a look at the existing [included ImageLoader](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/imageLoader).
5+
If you want to better understand how to implement your own ImageLoader, the easiest way would be to take a look at the existing [included ImageLoader](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/imageLoader).
6+
7+
## Included ImageLoader
8+
9+
### s3
10+
11+
The S3 ImageLoader will load images from an S3 bucket. It is used by default if you don't provide any ImageLoader in your configuration.
12+
It uses the `@aws-sdk/client-s3` to interact with S3.
13+
14+
##### Requirements
15+
16+
- You need to provide the `BUCKET_KEY_PREFIX`, `BUCKET_NAME` environment variables to your server.
17+
18+
### host
19+
20+
The Host ImageLoader will load images from the host.
21+
This implementation will directly fetch the image from the host.
22+
23+
##### Requirements
24+
25+
The host should be provided in the headers of the request, either in the `X-Forwarded-Host` or the `Host` header.
26+
27+
### fs-dev
28+
29+
The FsDev ImageLoader is a simple implementation that loads images from the `.open-next/assets` folder and interact with it using the filesystem. It is useful for development purposes only.
30+
31+
### dummy
32+
33+
The Dummy ImageLoader is a dummy implementation that will throw an exception. It should not be used.

‎pages/aws/config/overrides/incremental_cache.mdx‎

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,71 @@
1+
import { Callout } from 'nextra/components';
2+
13
This override is used by the [`cache` adapter](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/adapters/cache.ts) that is provided by OpenNext to the NextServer. It is also used by OpenNext if `enableCacheInterception` is set to `true` in the configuration.
24

35
It is used for retrieving and updating the ISR/SSG cache as well as the fetch cache used by Next.js. It does not handle anything related to cache tags (i.e. `revalidateTag` and `revalidatePath`)
46

57
If you want to better understand how to implement your own IncrementalCache, the easiest way would be to take a look at the existing [included IncrementalCache](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/incrementalCache).
68

79
One thing to note is that it is not used at build time, only at runtime. This means that you'll have to upload the cache yourself if you want to use the prebuilt routes/pages (And this is mandatory for ISR/SSG routes with `fallback:false`).
8-
All the cache files are present in the `.open-next/cache` folder. The one under `BUILD_ID` are for the ISR/SSG cache and the one under `__fetch/BUILD_ID` are for the fetch cache.
10+
All the cache files are present in the `.open-next/cache` folder. The one under `BUILD_ID` are for the ISR/SSG cache and the one under `__fetch/BUILD_ID` are for the fetch cache.
11+
12+
## Included IncrementalCache
13+
14+
### s3
15+
16+
The S3 IncrementalCache will store fetch and ISR/SSG cache in an S3 bucket. It is used by default if you don't provide any IncrementalCache in your configuration.
17+
It uses the `@aws-sdk/client-s3` to interact with S3.
18+
19+
##### Requirements
20+
21+
- You need to provide the `CACHE_BUCKET_REGION`, `CACHE_BUCKET_KEY_PREFIX`, `CACHE_BUCKET_NAME` environment variables to your server.
22+
23+
### s3-lite
24+
25+
The S3Lite IncrementalCache will store fetch and ISR/SSG cache in an S3 bucket
26+
This implementation is a lighter version of the `s3` IncrementalCache as it uses `aws4fetch` to interact with S3.
27+
28+
##### Requirements
29+
30+
- You need to provide the `CACHE_BUCKET_REGION`, `CACHE_BUCKET_KEY_PREFIX`, `CACHE_BUCKET_NAME`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables to your server.
31+
32+
### dummy
33+
34+
The Dummy IncrementalCache is a dummy implementation that throws exceptions for every method. It should not be used unless you want to disable the cache.
35+
36+
### fs-dev
37+
38+
The FsDev IncrementalCache is a simple implementation that stores the cache in the `.open-next/cache` folder and interact with it using the filesystem. It is useful for development purposes only.
39+
40+
##### Requirements
41+
42+
It needs to run on the local filesystem, and expect to be run from the OpenNext output.
43+
44+
### multi-tier-ddb-s3
45+
46+
<Callout type='warning'>
47+
Because of how it works, this implementation is only eventually consistent and errors during update could cause inconsistencies between the local cache in some instances and the S3 cache.
48+
49+
It could also end up being slower (and more expensive) than simpler implementations if used in a low traffic serverless environment.
50+
</Callout>
51+
52+
The MultiTierDdbS3 IncrementalCache is a more complex implementation.
53+
Cache are stored in a local In Memory LRU cache as well as in S3. DynamoDB is used to keep local cache in sync between multiple instances of the server.
54+
It uses `aws4fetch` to interact with S3 and DynamoDB.
55+
56+
##### How does it work
57+
58+
On get :
59+
1. When a cache is requested, it first checks the local cache. If the cache is not found, it will fetch it from S3 and store it in the local cache.
60+
2. If the local cache exist for this key, it will check metadata in DynamoDB to see if the cache is still valid. If it is not, it will fetch the cache from S3 and store it in the local cache.
61+
3. If the local cache is valid, it will return it.
62+
63+
On update :
64+
1. When a cache is updated, it will first try to update the cache in S3.
65+
2. If the update is successful, it will update the metadata in DynamoDB.
66+
3. Finally, it will update the local cache.
67+
68+
##### Requirements
69+
70+
- You need to provide the `CACHE_BUCKET_REGION`, `CACHE_BUCKET_KEY_PREFIX`, `CACHE_BUCKET_NAME`, `CACHE_DYNAMO_TABLE`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN`, `OPEN_NEXT_LOCAL_CACHE_TTL_MS` (optional), `OPEN_NEXT_LOCAL_CACHE_SIZE`(optional) environment variables to your server.
71+
- DynamoDB table should have a primary key `path` of type `String` and a sort key `tag` of type `String`. (It can reuse the same table as the one used by the default `tagCache`)

‎pages/aws/config/overrides/queue.mdx‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,42 @@
1+
import {Callout} from 'nextra/components'
2+
13
This override is used by OpenNext to trigger the revalidation of stale routes.
24
Before sending the response to the client, OpenNext will check if the route is stale and if it is, it will call the queue override to revalidate the route.
35

46
If you want to better understand how to implement your own Queue, the easiest way would be to take a look at the existing [included Queue](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/queue).
57

68
Couple of things to note :
79
- The default implementation use an SQS queue. This has the main advantage of being able to control the concurrency of the revalidations as well as avoiding trigerring the revalidation multiple times for the same route.
8-
- You don't have to use a queue at all. You could trigger the revalidation directly in the Queue override itself. You can see a very simple implementation of this [in the `queue` override](/aws/contribute/local_run#devqueuets).
10+
- You don't have to use a queue at all. You could trigger the revalidation directly in the Queue override itself. You can see a very simple implementation of this [in the `queue` override](/aws/contribute/local_run#devqueuets).
11+
12+
## Included Queue
13+
14+
### sqs
15+
16+
The SQS Queue will send a message to an SQS queue for each route that needs to be revalidated. It is used by default if you don't provide any Queue in your configuration.
17+
It uses the `@aws-sdk/client-sqs` to interact with SQS.
18+
19+
#### Requirements
20+
21+
- You need to provide the `QUEUE_URL` environment variable to your server.
22+
23+
### sqs-lite
24+
25+
The SQSLite Queue will send a message to an SQS queue for each route that needs to be revalidated.
26+
This implementation is a lighter version of the `sqs` Queue as it uses `aws4fetch` to interact with SQS.
27+
28+
#### Requirements
29+
30+
- You need to provide the `QUEUE_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables to your server.
31+
32+
### direct
33+
34+
The Direct Queue will directly trigger the revalidation of the route in the Queue override itself. It is useful for development purposes and when you don't want to use a queue.
35+
36+
<Callout type='warning'>
37+
Be careful with this implementation as it could lead to multiple revalidations of the same route.
38+
</Callout>
39+
40+
### dummy
41+
42+
The Dummy Queue is a dummy implementation that will throw an exception. It should not be used unless you want to disable ISR.

‎pages/aws/config/overrides/tag_cache.mdx‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,34 @@ This also has the drawback of needing to prepopulate the cache with all the tags
99

1010
We might allow to choose how cache tags are handled in the future depending on the `TagCache` implementation. If you need this feature, feel free to open an issue on the [GitHub repository](https://github.com/opennextjs/opennextjs-aws).
1111

12-
If you want to better understand how to implement your own TagCache, the easiest way would be to take a look at the existing [included TagCache](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/tagCache).
12+
If you want to better understand how to implement your own TagCache, the easiest way would be to take a look at the existing [included TagCache](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/tagCache).
13+
14+
## Included TagCache
15+
16+
### dynamodb
17+
18+
The DynamoDB TagCache will store the cache tags in a DynamoDB table. It is used by default if you don't provide any TagCache in your configuration.
19+
It uses the `@aws-sdk/client-dynamodb` to interact with DynamoDB.
20+
21+
##### Requirements
22+
23+
- You need to provide the `CACHE_DYNAMO_TABLE`, `CACHE_BUCKET_REGION` environment variable to your server.
24+
- DynamoDB table should have a primary key `path` of type `String` and a sort key `tag` of type `String`. (It can reuse the same table as the one used by the default `tagCache`)
25+
26+
### dynamodb-lite
27+
28+
The DynamoDBLite TagCache will store the cache tags in a DynamoDB table.
29+
This implementation is a lighter version of the `dynamodb` TagCache as it uses `aws4fetch` to interact with DynamoDB.
30+
31+
##### Requirements
32+
33+
- You need to provide the `CACHE_DYNAMO_TABLE`, `CACHE_BUCKET_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables to your server.
34+
- DynamoDB table should have a primary key `path` of type `String` and a sort key `tag` of type `String`. (It can reuse the same table as the one used by the default `tagCache`)
35+
36+
### dummy
37+
38+
The Dummy TagCache is a dummy implementation that will throw an exception. It should not be used unless you want to disable cache tags.
39+
40+
### fs-dev
41+
42+
The FsDev TagCache is a simple implementation that stores the cache tags in a file in the `.open-next/cache` folder and interact with it using the filesystem. It is useful for development purposes only.

‎pages/aws/config/overrides/wrapper.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,62 @@ Couple of things to note :
77
- If you don't use streaming (like in the default `aws-lambda` wrapper), you may still need to provide a fake `StreamCreator` to the `handler` to avoid a weird issue with Node itself (see [here](https://github.com/opennextjs/opennextjs-aws/blob/f685ddea8f8a5c82591dc02713aff7138f2d9896/packages/open-next/src/overrides/wrappers/aws-lambda.ts#L49-L65) for an example and a more thorough explanation).
88
- If you use the `edge` runtime of Next (either for the external middleware or for an `edge` route or page), you don't need the `StreamCreator` at all.
99
- If you are in a serverless environment and it supports `waitUntil`, you should define it here(see [here](https://github.com/opennextjs/opennextjs-aws/blob/f685ddea8f8a5c82591dc02713aff7138f2d9896/packages/open-next/src/overrides/wrappers/cloudflare.ts#L29)). This might not be necessary depending on where you run it (for example the `aws-lambda-streaming` or the `node` wrapper doesn't need it.)
10+
11+
12+
## Included Wrappers
13+
14+
### aws-lambda
15+
16+
The `aws-lambda` Wrapper is the default wrapper for AWS Lambda. It is used by default if you don't provide any Wrapper in your configuration.
17+
18+
#### Features
19+
- [ ] Streaming
20+
- [ ] Proper support for `waitUntil`
21+
22+
### aws-lambda-streaming
23+
24+
The `aws-lambda-streaming` Wrapper is a wrapper that allows you to use streaming in AWS Lambda. Streaming must be enabled for this lambda.
25+
26+
#### Features
27+
- [x] Streaming
28+
- [x] Proper support for `waitUntil`
29+
30+
### cloudflare-edge
31+
32+
The `cloudflare-edge` Wrapper is the wrapper for Cloudflare Workers. It should be used for the external middleware and for the `edge` runtime of Next.
33+
34+
#### Features
35+
- [x] Streaming
36+
- [x] Proper support for `waitUntil`
37+
38+
### cloudflare-node
39+
40+
The `cloudflare-node` Wrapper is the wrapper for Cloudflare Workers. It should be used only with the `node` runtime of Next and if you use `@opennextjs/cloudflare`.
41+
42+
#### Features
43+
- [x] Streaming
44+
- [x] Proper support for `waitUntil`
45+
46+
### node
47+
48+
The `node` Wrapper is the wrapper for classic Node.js Server. This one is a long running server.
49+
50+
#### Features
51+
- [x] Streaming
52+
- [x] Proper support for `waitUntil`
53+
54+
### express-dev
55+
56+
The `express-dev` Wrapper is the wrapper for a classic Express server. It is a long running process and should be used for development purposes only.
57+
58+
#### Features
59+
- [x] Streaming
60+
- [x] Proper support for `waitUntil`
61+
62+
### dummy
63+
64+
The `dummy` Wrapper is a dummy implementation that will just forward the event and `StreamCreator` to the handler.
65+
66+
#### Features
67+
- [ ] Streaming
68+
- [ ] Proper support for `waitUntil`

0 commit comments

Comments
 (0)