carlin 2.2.2 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.mjs +125 -11
  2. package/package.json +5 -5
package/dist/index.mjs CHANGED
@@ -3586,6 +3586,76 @@ const APPEND_INDEX_HTML_HELPER = `function appendIndexHtml(request) {
3586
3586
  return request;
3587
3587
  }`;
3588
3588
  /**
3589
+ * `redirectToTrailingSlash` injected into every app-supplied viewer request
3590
+ * function, and the whole behavior of the `redirectToTrailingSlash` option.
3591
+ *
3592
+ * `appendIndexHtml` answers `/docs/guide` and `/docs/guide/` with the same
3593
+ * object, so every page of a site has a duplicate that search engines crawl and
3594
+ * have to de-duplicate, and nothing signals a link written without the trailing
3595
+ * slash. This helper serves the trailing slash form as `appendIndexHtml` does
3596
+ * and redirects the extension-less one to it, so a page answers on one URL.
3597
+ *
3598
+ * The query string is carried over verbatim — the values CloudFront exposes are
3599
+ * the ones the viewer sent, so re-encoding them would double-encode a
3600
+ * `?utm_content=a%20b`, and dropping them would break attribution on the
3601
+ * redirected request. A parameter sent without a value (`?flag`) is rebuilt as
3602
+ * `?flag=`, which every query string parser reads the same way.
3603
+ *
3604
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-event-structure.html
3605
+ */
3606
+ const REDIRECT_TO_TRAILING_SLASH_HELPER = `function redirectToTrailingSlash(request) {
3607
+ var uri = request.uri;
3608
+
3609
+ if (uri.endsWith('/')) {
3610
+ request.uri += 'index.html';
3611
+ return request;
3612
+ }
3613
+
3614
+ if (uri.includes('.')) {
3615
+ return request;
3616
+ }
3617
+
3618
+ var querystring = '';
3619
+
3620
+ for (var name in request.querystring) {
3621
+ var parameter = request.querystring[name];
3622
+ var values = parameter.multiValue || [parameter];
3623
+
3624
+ for (var i = 0; i < values.length; i++) {
3625
+ querystring += (querystring ? '&' : '?') + name + '=' + values[i].value;
3626
+ }
3627
+ }
3628
+
3629
+ return {
3630
+ statusCode: 301,
3631
+ statusDescription: 'Moved Permanently',
3632
+ headers: { location: { value: uri + '/' + querystring } },
3633
+ };
3634
+ }`;
3635
+ /**
3636
+ * Code of the per-app function the `redirectToTrailingSlash` option creates.
3637
+ *
3638
+ * The redirect cannot go into the shared base stack function the
3639
+ * `appendIndexHtml` option associates: that one is imported by ARN by every
3640
+ * static app in the account, so changing it would redirect all of them at once,
3641
+ * on someone else's version bump. A per-app function keeps the choice with the
3642
+ * app, and costs no base stack update before the option can be used.
3643
+ */
3644
+ const REDIRECT_TO_TRAILING_SLASH_FUNCTION_CODE = `${REDIRECT_TO_TRAILING_SLASH_HELPER}
3645
+
3646
+ function handler(event) {
3647
+ return redirectToTrailingSlash(event.request);
3648
+ }
3649
+ `;
3650
+ /**
3651
+ * Helpers carlin makes available to an app-supplied function, in the order they
3652
+ * are injected. They count against the size budget of every function, so a
3653
+ * helper is added here only when it holds behavior an option of carlin also
3654
+ * provides — an app that supplies its own function can reach for it instead of
3655
+ * losing the option.
3656
+ */
3657
+ const INJECTED_HELPERS = [APPEND_INDEX_HTML_HELPER, REDIRECT_TO_TRAILING_SLASH_HELPER].join("\n\n");
3658
+ /**
3589
3659
  * The entry point CloudFront calls. A function whose code doesn't declare it
3590
3660
  * fails at deploy time with an opaque error, so it's checked at synth time.
3591
3661
  */
@@ -3599,19 +3669,19 @@ const readViewerRequestFunctionCode = ({ filePath }) => {
3599
3669
  return fs.readFileSync(resolvedPath, "utf8");
3600
3670
  };
3601
3671
  /**
3602
- * Composes the source of the per-app `AWS::CloudFront::Function`: the
3603
- * `appendIndexHtml` helper followed by the app code, which owns the `handler`.
3672
+ * Composes the source of the per-app `AWS::CloudFront::Function`: the injected
3673
+ * helpers followed by the app code, which owns the `handler`.
3604
3674
  */
3605
3675
  const getViewerRequestFunctionCode = ({ code }) => {
3606
3676
  if (!code.trim()) throw new Error("The viewer-request-function-code option points to an empty file.");
3607
3677
  if (!HANDLER_DECLARATION_REGEX.test(code)) throw new Error("The viewer request function code must declare a `function handler(event)`, which is the entry point CloudFront calls.");
3608
- const functionCode = `${APPEND_INDEX_HTML_HELPER}\n\n${code.trim()}\n`;
3678
+ const functionCode = `${INJECTED_HELPERS}\n\n${code.trim()}\n`;
3609
3679
  /**
3610
- * The helper counts against the app budget, so the size of the composed
3680
+ * The helpers count against the app budget, so the size of the composed
3611
3681
  * source is what CloudFront rejects.
3612
3682
  */
3613
3683
  const size = Buffer.byteLength(functionCode, "utf8");
3614
- if (size > 10240) throw new Error(`The viewer request function is ${size} bytes, above the ${MAX_FUNCTION_SIZE_BYTES} bytes CloudFront allows. The \`appendIndexHtml\` helper carlin injects counts against this budget.`);
3684
+ if (size > 10240) throw new Error(`The viewer request function is ${size} bytes, above the ${MAX_FUNCTION_SIZE_BYTES} bytes CloudFront allows. The helpers carlin injects count against this budget.`);
3615
3685
  return functionCode;
3616
3686
  };
3617
3687
  //#endregion
@@ -3719,7 +3789,7 @@ const getBucketStaticWebsiteTemplate = ({ spa }) => {
3719
3789
  } }
3720
3790
  };
3721
3791
  };
3722
- const getCloudFrontTemplate = ({ acm, aliases = [], appendIndexHtml, responseHeaders = [], responseHeadersPolicy, spa, hostedZoneName, viewerRequestFunctionCode }) => {
3792
+ const getCloudFrontTemplate = ({ acm, aliases = [], appendIndexHtml, redirectToTrailingSlash, responseHeaders = [], responseHeadersPolicy, spa, hostedZoneName, viewerRequestFunctionCode }) => {
3723
3793
  const template = {
3724
3794
  AWSTemplateFormatVersion: "2010-09-09",
3725
3795
  Resources: {
@@ -3913,7 +3983,28 @@ const getCloudFrontTemplate = ({ acm, aliases = [], appendIndexHtml, responseHea
3913
3983
  * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-function-restrictions-all.html
3914
3984
  */
3915
3985
  if (appendIndexHtml && viewerRequestFunctionCode) throw new Error("The append-index-html and viewer-request-function-code options are mutually exclusive. A cache behavior takes a single viewer request function. Call `appendIndexHtml(request)` from your function instead, which carlin injects for you.");
3916
- if (viewerRequestFunctionCode) template.Resources[CLOUDFRONT_VIEWER_REQUEST_FUNCTION_LOGICAL_ID] = {
3986
+ /**
3987
+ * The redirect is a mode of the index appending, not a behavior of its own:
3988
+ * it still serves `/docs/guide/` as `/docs/guide/index.html`, and only
3989
+ * changes what answers `/docs/guide`.
3990
+ */
3991
+ if (redirectToTrailingSlash && !appendIndexHtml) throw new Error("The redirect-to-trailing-slash option requires the append-index-html option. It changes how an extension-less URI is answered, so the index appending it redirects to has to be on.");
3992
+ /**
3993
+ * An extension-less URI of a SPA is a client route rather than a directory,
3994
+ * so redirecting it to a trailing slash would move every route of the app to
3995
+ * a URL its router doesn't produce.
3996
+ */
3997
+ if (redirectToTrailingSlash && spa) throw new Error("The redirect-to-trailing-slash and spa options are mutually exclusive. An extension-less URI of a SPA is a client route, not a directory, so redirecting it to a trailing slash changes the URL of every route.");
3998
+ /**
3999
+ * The redirect cannot go into the shared base stack function, which every
4000
+ * static app of the account imports by ARN, so it is deployed as a function
4001
+ * of this app instead.
4002
+ */
4003
+ const perAppFunctionCode = (() => {
4004
+ if (viewerRequestFunctionCode) return getViewerRequestFunctionCode({ code: viewerRequestFunctionCode });
4005
+ if (redirectToTrailingSlash) return REDIRECT_TO_TRAILING_SLASH_FUNCTION_CODE;
4006
+ })();
4007
+ if (perAppFunctionCode) template.Resources[CLOUDFRONT_VIEWER_REQUEST_FUNCTION_LOGICAL_ID] = {
3917
4008
  Type: "AWS::CloudFront::Function",
3918
4009
  Properties: {
3919
4010
  /**
@@ -3926,12 +4017,12 @@ const getCloudFrontTemplate = ({ acm, aliases = [], appendIndexHtml, responseHea
3926
4017
  Comment: { "Fn::Sub": ["Viewer request function for the ${Project} project.", { Project: { Ref: "Project" } }] },
3927
4018
  Runtime: FUNCTION_RUNTIME
3928
4019
  },
3929
- FunctionCode: getViewerRequestFunctionCode({ code: viewerRequestFunctionCode }),
4020
+ FunctionCode: perAppFunctionCode,
3930
4021
  AutoPublish: true
3931
4022
  }
3932
4023
  };
3933
4024
  const viewerRequestFunctionArn = (() => {
3934
- if (viewerRequestFunctionCode) return { "Fn::GetAtt": [CLOUDFRONT_VIEWER_REQUEST_FUNCTION_LOGICAL_ID, "FunctionMetadata.FunctionARN"] };
4025
+ if (perAppFunctionCode) return { "Fn::GetAtt": [CLOUDFRONT_VIEWER_REQUEST_FUNCTION_LOGICAL_ID, "FunctionMetadata.FunctionARN"] };
3935
4026
  if (appendIndexHtml) return { "Fn::ImportValue": BASE_STACK_CLOUDFRONT_FUNCTION_APPEND_INDEX_HTML_ARN_EXPORTED_NAME };
3936
4027
  })();
3937
4028
  if (viewerRequestFunctionArn) {
@@ -3957,12 +4048,13 @@ const getCloudFrontTemplate = ({ acm, aliases = [], appendIndexHtml, responseHea
3957
4048
  };
3958
4049
  return template;
3959
4050
  };
3960
- const getStaticAppTemplate = ({ acm, aliases, appendIndexHtml, cloudfront, responseHeaders, responseHeadersPolicy, spa, hostedZoneName, region, viewerRequestFunctionCode }) => {
4051
+ const getStaticAppTemplate = ({ acm, aliases, appendIndexHtml, cloudfront, redirectToTrailingSlash, responseHeaders, responseHeadersPolicy, spa, hostedZoneName, region, viewerRequestFunctionCode }) => {
3961
4052
  if (cloudfront) return getCloudFrontTemplate({
3962
4053
  acm,
3963
4054
  aliases,
3964
4055
  appendIndexHtml,
3965
4056
  cloudfront,
4057
+ redirectToTrailingSlash,
3966
4058
  responseHeaders,
3967
4059
  responseHeadersPolicy,
3968
4060
  spa,
@@ -4040,7 +4132,7 @@ const logPrefix$4 = "static-app";
4040
4132
  * 1. Upload static files to the host bucket S3.
4041
4133
  * 1. Remove old deployment versions. Keep only the 3 most recent ones.
4042
4134
  */
4043
- const deployStaticApp = async ({ acm, aliases, appendIndexHtml, buildFolder, cloudfront, responseHeaders, responseHeadersPolicy, spa, hostedZoneName, region, skipUpload, uploadSourceMaps, viewerRequestFunctionCode }) => {
4135
+ const deployStaticApp = async ({ acm, aliases, appendIndexHtml, buildFolder, cloudfront, redirectToTrailingSlash, responseHeaders, responseHeadersPolicy, spa, hostedZoneName, region, skipUpload, uploadSourceMaps, viewerRequestFunctionCode }) => {
4044
4136
  try {
4045
4137
  const { stackName } = await handleDeployInitialization({ logPrefix: logPrefix$4 });
4046
4138
  const params = { StackName: stackName };
@@ -4049,6 +4141,7 @@ const deployStaticApp = async ({ acm, aliases, appendIndexHtml, buildFolder, clo
4049
4141
  aliases,
4050
4142
  appendIndexHtml,
4051
4143
  cloudfront,
4144
+ redirectToTrailingSlash,
4052
4145
  responseHeaders,
4053
4146
  responseHeadersPolicy,
4054
4147
  spa,
@@ -4142,6 +4235,11 @@ const options$4 = {
4142
4235
  hidden: true,
4143
4236
  type: "string"
4144
4237
  },
4238
+ "redirect-to-trailing-slash": {
4239
+ default: false,
4240
+ describe: "Answer an extension-less request URI with a `301` to its trailing slash form instead of serving the page on both, so each page of the site has a single URL. Requires the `append-index-html` option.",
4241
+ type: "boolean"
4242
+ },
4145
4243
  "response-headers": {
4146
4244
  coerce: parseResponseHeaders,
4147
4245
  default: [],
@@ -4192,6 +4290,22 @@ const deployStaticAppCommand = {
4192
4290
  */
4193
4291
  if (!cloudfront && (hasResponseHeaders || responseHeadersPolicy)) throw new Error(`The ${hasResponseHeaders ? "response-headers" : "response-headers-policy"} option requires the cloudfront option.`);
4194
4292
  return true;
4293
+ }).check(({ appendIndexHtml, redirectToTrailingSlash, spa }) => {
4294
+ if (!redirectToTrailingSlash) return true;
4295
+ /**
4296
+ * The redirect is a mode of the index appending, not a behavior of
4297
+ * its own: it still serves `/docs/guide/` as
4298
+ * `/docs/guide/index.html`, and only changes what answers
4299
+ * `/docs/guide`.
4300
+ */
4301
+ if (!appendIndexHtml) throw new Error("The redirect-to-trailing-slash option requires the append-index-html option. It changes how an extension-less URI is answered, so the index appending it redirects to has to be on.");
4302
+ /**
4303
+ * An extension-less URI of a SPA is a client route rather than a
4304
+ * directory, so redirecting it to a trailing slash would move every
4305
+ * route of the app to a URL its router doesn't produce.
4306
+ */
4307
+ if (spa) throw new Error("The redirect-to-trailing-slash and spa options are mutually exclusive. An extension-less URI of a SPA is a client route, not a directory, so redirecting it to a trailing slash changes the URL of every route.");
4308
+ return true;
4195
4309
  }).check(({ appendIndexHtml, cloudfront, viewerRequestFunctionCode }) => {
4196
4310
  if (!viewerRequestFunctionCode) return true;
4197
4311
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "carlin",
3
- "version": "2.2.2",
3
+ "version": "2.4.0",
4
4
  "description": "",
5
5
  "keywords": [],
6
6
  "homepage": "https://ttoss.dev/docs/carlin/",
@@ -57,9 +57,9 @@
57
57
  "ts-node": "^10.9.2",
58
58
  "uglify-js": "^3.19.3",
59
59
  "yargs": "^17.7.2",
60
- "@ttoss/cloudformation": "^0.13.11",
61
- "@ttoss/config": "^1.37.17",
62
- "@ttoss/read-config-file": "^2.2.20"
60
+ "@ttoss/cloudformation": "^0.14.0",
61
+ "@ttoss/read-config-file": "^2.3.0",
62
+ "@ttoss/config": "^1.38.0"
63
63
  },
64
64
  "devDependencies": {
65
65
  "@types/adm-zip": "^0.5.6",
@@ -79,7 +79,7 @@
79
79
  "jest": "^30.4.2",
80
80
  "tsdown": "^0.22.2",
81
81
  "typescript": "~6.0.3",
82
- "@ttoss/test-utils": "^4.2.18"
82
+ "@ttoss/test-utils": "^4.2.19"
83
83
  },
84
84
  "publishConfig": {
85
85
  "access": "public",