jskelet 0.6.11 → 0.6.12

package/CHANGELOG.md

@@ -19,9 +19,11 @@ one is listed under a **Breaking** heading.
   `JSKELET_S3_*`, then ECS task-role / EC2 instance-profile metadata). The
   Assets upload step always appears on production builds; when off it logs a
   one-line reason (`skipped (no build.assets.upload.bucket)`,
-  `skipped (credentials missing)`, …). A URL in `upload.bucket` is rejected
-  with a warning (CDN origin belongs in `prefix`). Watch mode never uploads.
-  `.br` / `.gz` siblings are skipped.
+  `skipped (credentials missing (no env keys, no ECS task role …))`, …).
+  Docker/`RUN jskelet build` has no task role — upload needs CI role or a
+  runtime upload. A URL in `upload.bucket` is rejected with a warning (CDN
+  origin belongs in `prefix`). Watch mode never uploads. `.br` / `.gz`
+  siblings are skipped.
 
 ### Changed
 

package/docs/10-dagitim.md

@@ -55,34 +55,41 @@ ayarlamayı düşünmeniz gerekenler:
 
 ### Asset'leri S3 / CloudFront'a basmak
 
-Varsayılan kapalıdır. Config'te prefix + bucket; CI'da yalnızca credential:
+Varsayılan kapalıdır. Config'te prefix + bucket; credential env key **veya**
+IAM role:
 
 ```js
-// jskelet.config.mjs
+// jskelet.config.mjs — uygulama env'lerini buraya bağla
 build: {
   assets: {
-    prefix: "https://static.ornek.com/js",
+    prefix: process.env.NEXT_PUBLIC_STATIC_ASSETS_BASE_URL, // https://static.…
     upload: {
-      bucket: "static.ornek.com", // veya "static.ornek.com/js"
+      bucket: process.env.S3_BUCKET_NAME, // static.investvio.com
       keyPrefix: "js",
-      region: "eu-central-1",
+      region: process.env.AWS_REGION || "eu-central-1",
+      endpoint: process.env.AWS_S3_ENDPOINT || undefined,
     },
   },
 },
 ```
 
-```bash
-# CI / local: explicit keys. ECS/EC2'de task/instance role yeter — key şart değil.
-AWS_ACCESS_KEY_ID=…
-AWS_SECRET_ACCESS_KEY=…
-# AWS_SESSION_TOKEN=…
-```
+**Task role ne zaman çalışır?** ECS task role /
+`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` yalnızca **görev çalışırken** vardır.
+Dockerfile içindeki `RUN jskelet build` veya CI build agent'ında bu URI
+yoktur → `skipped (credentials missing (no env keys, no ECS task role …))`.
+AWS SDK'nın runtime'da rolü görmesi, build adımının rolü görmesi demek değildir.
+
+Pratik seçenekler:
+
+1. **CI'da rol ile build** (CodeBuild / GitHub OIDC) — static key yok, upload
+   build job'unda biter.
+2. **Image'da yalnızca derle**, upload'u ECS start'ta ayrı koş (task role o an
+   vardır).
+3. CI'da geçici `AWS_*` key (tercih edilmez).
 
-`jskelet build` bitince `public/assets/` (ve config'te `include` edilen
-dizinler) S3'e kopyalanır; origin'deki dosyalar da durur. Bucket veya
-credential yoksa adım `skipped (…)` ile sebep basar, build devam eder. Watch /
-`jskelet dev` upload yapmaz. CSP kullanıyorsanız CDN origin'ini `script-src` /
-`style-src` / `img-src` ve `preconnect` listesine ekleyin.
+`jskelet build` bitince `public/assets/` S3'e kopyalanır; origin kopyası durur.
+Bucket/credential yoksa adım `skipped (…)` basar. Watch / `jskelet dev` upload
+yapmaz. CSP'ye CDN origin ekleyin.
 
 Production'da dosya veya S3 sink açıldığında HTTP access log middleware
 otomatik mount edilir (`logs.kinds` içinde `http` varsa). Admin paneli ring'i

package/docs/en/10-deployment.md

@@ -56,34 +56,40 @@ considering in production:
 
 ### Publishing assets to S3 / CloudFront
 
-Off by default. Prefix + bucket in config; credentials only in CI:
+Off by default. Prefix + bucket in config; credentials from env keys **or** an
+IAM role:
 
 ```js
-// jskelet.config.mjs
+// jskelet.config.mjs — wire your app env vars here
 build: {
   assets: {
-    prefix: "https://static.example.com/js",
+    prefix: process.env.NEXT_PUBLIC_STATIC_ASSETS_BASE_URL, // https://static.…
     upload: {
-      bucket: "static.example.com", // or "static.example.com/js"
+      bucket: process.env.S3_BUCKET_NAME, // static.example.com
       keyPrefix: "js",
-      region: "eu-central-1",
+      region: process.env.AWS_REGION || "eu-central-1",
+      endpoint: process.env.AWS_S3_ENDPOINT || undefined,
     },
   },
 },
 ```
 
-```bash
-# CI / local: explicit keys. On ECS/EC2 a task/instance role is enough — no keys required.
-AWS_ACCESS_KEY_ID=…
-AWS_SECRET_ACCESS_KEY=…
-# AWS_SESSION_TOKEN=…
-```
+**When does the task role work?** The ECS task role /
+`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` exist only while the **task is
+running**. A `RUN jskelet build` inside Docker or a CI build agent has no such
+URI → `skipped (credentials missing (no env keys, no ECS task role …))`. The AWS
+SDK seeing the role at runtime does not mean the build step sees it.
+
+Practical options:
+
+1. **Build with a CI role** (CodeBuild / GitHub OIDC) — no static keys; upload
+   finishes in the job.
+2. **Compile in the image**, run upload at ECS start (task role is present then).
+3. Temporary `AWS_*` keys in CI (not preferred).
 
-When `jskelet build` finishes, files under `public/assets/` (and any other
-`include` directories) are copied to S3; origin copies remain. If the bucket or
-credentials are missing, the step logs `skipped (…)` with the reason and the
-build continues. Watch / `jskelet dev` never upload. If you use CSP, add the CDN
-origin to `script-src` / `style-src` / `img-src` and to `preconnect`.
+When `jskelet build` finishes, `public/assets/` is copied to S3; origin copies
+remain. Missing bucket/credentials log `skipped (…)`. Watch / `jskelet dev`
+never upload. Add the CDN origin to CSP.
 
 When a file or S3 sink is enabled in production, the HTTP access log middleware
 mounts automatically (if `http` is in `logs.kinds`). The admin panel ring is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk SSR (optional EJS peer), vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/build/tasks/assets-upload.mjs

@@ -12,7 +12,10 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { resolveS3Credentials } from "../../server/logs/s3-credentials.js";
+import {
+  resolveS3Credentials,
+  s3CredentialsMissingReason,
+} from "../../server/logs/s3-credentials.js";
 import { putObject } from "../../server/logs/s3-put.js";
 import * as log from "../../log.mjs";
 import { paths } from "../paths.mjs";
@@ -127,7 +130,7 @@ export async function uploadAssets(config, options = {}) {
   const resolve = options.resolveCredentials ?? resolveS3Credentials;
   const credentials = await resolve();
   if (!upload.bucket || !credentials) {
-    log.detail("skipped (credentials missing)");
+    log.detail(`skipped (${s3CredentialsMissingReason()})`);
     return;
   }
 

package/src/server/logs/s3-credentials.js

@@ -16,7 +16,9 @@ import process from "node:process";
  *   sessionToken: string | null }} AwsCredentials
  */
 
-const METADATA_TIMEOUT_MS = 400;
+// Local'de IMDS yokken hızlı vazgeç; ECS'te URI varken biraz daha sabır.
+const IMDS_TIMEOUT_MS = 400;
+const ECS_TIMEOUT_MS = 2_000;
 const ECS_METADATA_HOST = "http://169.254.170.2";
 const EC2_METADATA_HOST = "http://169.254.169.254";
 
@@ -72,7 +74,7 @@ function fromAwsCredentialJson(data) {
  * @param {number} [timeoutMs]
  * @returns {Promise<unknown | null>}
  */
-async function fetchJson(url, init = {}, timeoutMs = METADATA_TIMEOUT_MS) {
+async function fetchJson(url, init = {}, timeoutMs = IMDS_TIMEOUT_MS) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -92,7 +94,7 @@ async function fetchJson(url, init = {}, timeoutMs = METADATA_TIMEOUT_MS) {
  * @param {number} [timeoutMs]
  * @returns {Promise<string | null>}
  */
-async function fetchText(url, init = {}, timeoutMs = METADATA_TIMEOUT_MS) {
+async function fetchText(url, init = {}, timeoutMs = IMDS_TIMEOUT_MS) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -125,7 +127,7 @@ export async function readS3CredentialsFromEcs() {
     readTokenFile(process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE);
   if (token) headers.Authorization = token;
 
-  const data = await fetchJson(url, { headers });
+  const data = await fetchJson(url, { headers }, ECS_TIMEOUT_MS);
   if (!data || typeof data !== "object") return null;
   return fromAwsCredentialJson(/** @type {Record<string, unknown>} */ (data));
 }
@@ -179,6 +181,21 @@ export async function readS3CredentialsFromImds() {
   return fromAwsCredentialJson(/** @type {Record<string, unknown>} */ (data));
 }
 
+/**
+ * Credential neden bulunamadı — upload skip satırı için.
+ *
+ * @returns {string}
+ */
+export function s3CredentialsMissingReason() {
+  if (
+    envText(process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI) ||
+    envText(process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI)
+  ) {
+    return "credentials missing (ECS metadata failed)";
+  }
+  return "credentials missing (no env keys, no ECS task role — upload needs runtime/CI role, not docker build)";
+}
+
 /**
  * Env → ECS task role → EC2 instance profile.
  *

package/types/server/logs/s3-credentials.d.ts

@@ -19,6 +19,12 @@ export declare function readS3CredentialsFromEcs(): Promise<AwsCredentials | nul
  * @returns {Promise<AwsCredentials | null>}
  */
 export declare function readS3CredentialsFromImds(): Promise<AwsCredentials | null>;
+/**
+ * Credential neden bulunamadı — upload skip satırı için.
+ *
+ * @returns {string}
+ */
+export declare function s3CredentialsMissingReason(): string;
 /**
  * Env → ECS task role → EC2 instance profile.
  *