refactor: overrides (#79)

Co-authored-by: conico974 <[email protected]>

Author: sommeeeer

pages/aws/config/overrides/automatic_cdn_invalidation.mdx

@@ -2,7 +2,7 @@ import {Callout} from 'nextra/components'
 
 Available since `@opennextjs/aws` 3.4.0
 
-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.
+Not enabled by default. 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.
 It will be called for `revalidatePath`, `revalidateTag` and `res.revalidate()`.
 
 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)

pages/aws/config/overrides/converter.mdx

@@ -6,4 +6,34 @@ Couple of things to note :
 - If you use a `StreamCreator` in your wrapper, you probably don't need to do anything in the `convertTo` function.
 - If used for the default, the image optimization, or one of the splitted server the internal types will be `InternalEvent` and `InternalResult` respectively.
 - If used for the external middleware, the internal types will be `InternalEvent` and `InternalResult | MiddlewareResult` respectively.
-- For the other servers, look up their respective types in the codebase.
+- For the other servers, look up their respective types in the codebase.
+
+## Included Converters
+
+### aws-apigw-v2
+
+The `aws-apigw-v2` Converter is the default convert for AWS. It is used by default if you don't provide any Converter in your configuration.
+
+### aws-apigw-v1
+
+The `aws-apigw-v1` Converter is a converter that allows you to convert request and response from Amazon API Gateway v1.
+
+### aws-cloudfront
+
+The `aws-cloudfront` Converter is a converter for Cloudfront (i.e. lambda@edge)
+
+### edge
+
+The `edge` Converter is the converter for everything that uses `Request` and `Response`. At the moment with the builtin one that's only Cloudflare.
+
+### converter
+
+The `node` Converter is a converter for classic Node.js server.
+
+### sqs-revalidate
+
+The `sqs-revalidate` Converter is a converter for the Revalidation server. It uses SQS Queue to handle the revalidation.
+
+### dummy
+
+The `dummy` Converter is a dummy implementation that will just forward the request and response as is.

pages/aws/config/overrides/image_loader.mdx

@@ -15,6 +15,15 @@ It uses the `@aws-sdk/client-s3` to interact with S3.
 
 - You need to provide the `BUCKET_KEY_PREFIX`, `BUCKET_NAME` environment variables to your server.
 
+### s3-lite
+
+The `s3-lite` ImageLoader will load images from an S3 bucket. It uses the `aws4fetch` to interact with S3.
+
+##### Requirements
+
+- You need to provide the `BUCKET_KEY_PREFIX`, `BUCKET_NAME` environment variables to your server. 
+- Can also provide `BUCKET_REGION`. It fallbacks to `AWS_REGION` ?? `AWS_DEFAULT_REGION`. This should be set by AWS automatically. You can read more about how this works on AWS Lambdas [here](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime).
+
 ### host
 
 The Host ImageLoader will load images from the host.

pages/aws/config/overrides/proxy_external_request.mdx

@@ -1,3 +1,17 @@
 This override is used by OpenNext to proxy rewritten requests to external services. It is used either in the `external` middleware (if set) or in the default/splitted server if the middleware is bundled.
 
-If you want to better understand how to implement your own ProxyExternalRequest, the easiest way would be to take a look at the existing [included ProxyExternalRequest](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/proxyExternalRequest).
+If you want to better understand how to implement your own ProxyExternalRequest, the easiest way would be to take a look at the existing [included ProxyExternalRequest](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/proxyExternalRequest).
+
+## Included Proxy External Request
+
+### node
+
+This uses node-proxy to proxy the request to the external service.
+
+### fetch
+
+This uses fetch to proxy the request to the external service. It doesn't work in Node.js
+
+### dummy
+
+This is a dummy implementation that throws a FatalError.

pages/aws/config/overrides/queue.mdx

@@ -7,7 +7,7 @@ If you want to better understand how to implement your own Queue, the easiest wa
 
 Couple of things to note :
 - 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.
-- 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).
+- 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 `direct` override](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/queue/direct.ts).
 
 ## Included Queue
 
@@ -18,7 +18,7 @@ It uses the `@aws-sdk/client-sqs` to interact with SQS.
 
 #### Requirements
 
-- You need to provide the `QUEUE_URL` environment variable to your server.
+- You need to provide the `REVALIDATION_QUEUE_URL` environment variable to your server.
 
 ### sqs-lite
 
@@ -27,7 +27,7 @@ This implementation is a lighter version of the `sqs` Queue as it uses `aws4fetc
 
 #### Requirements
 
-- You need to provide the `QUEUE_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables to your server.
+- You need to provide the `REVALIDATION_QUEUE_URL`, `REVALIDATION_QUEUE_REGION`(will fallback to `us-east-1`), `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables to your server.
 
 ### direct
 

pages/aws/config/overrides/tag_cache.mdx

@@ -1,7 +1,7 @@
 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 and by the `initializationFunction` for prepopulating the cache.
 
 It is used for the cache tags (i.e. `revalidateTag` and `revalidatePath`). It does not handle anything related to the ISR/SSG cache or the fetch cache used by Next.js.
-It's main role is to detremine if a path is stale based on the tags and also to update the tag cache when `revalidateTag` is called.
+It's main role is to determine if a path is stale based on the tags and also to update the tag cache when `revalidateTag` is called.
 
 The current implementation differs from the way Next.js standalone handle cache tags. In the standalone version, the cache tags are stored in a file, and every time a cache entry is accessed, it has to check for every tags if the entry is stale. This approach is very read heavy and doesn't work well with DB like DynamoDB.
 We choose to go another way. We store tags for every path that exists in the cache. This way, we can easily know if a path is stale by just checking the path instead of every tags used. This approach is more write heavy but it's a tradeoff we are willing to make.
@@ -33,10 +33,14 @@ This implementation is a lighter version of the `dynamodb` TagCache as it uses `
 - 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.
 - 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`)
 
+### dynamodb-nextMode
+
+TBA
+
 ### dummy
 
 The Dummy TagCache is a dummy implementation that will throw an exception. It should not be used unless you want to disable cache tags.
 
 ### fs-dev
 
-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.
+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

@@ -6,7 +6,7 @@ Couple of things to note :
 - If you want to use streaming (for the `node` runtime of next), you'll need to create a `StreamCreator` and pass it to the `handler`. You can find some example in the [node](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/wrappers/node.ts) or [aws-lambda-streaming](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/wrappers/aws-lambda-streaming.ts) wrapper.
 - 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).
 - 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.
-- 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.)
+- 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/b0b1f7776b41612d2638a33e3c9ced8c42afab0a/packages/open-next/src/overrides/wrappers/cloudflare-node.ts#L80). 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.)
 
 
 ## Included Wrappers