@usejourney/core 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -416,6 +416,11 @@ interface HttpContext {
      * `timeoutMs` always overrides this.
      */
     defaultTimeoutMs?: number | null;
+    /**
+     * Directory that relative `fileFrom()` paths resolve against. The CLI sets
+     * it to the project root; unset falls back to `process.cwd()`.
+     */
+    baseDir?: string;
 }
 /** Fallback request timeout (ms) when neither a step nor `HttpContext.defaultTimeoutMs` set one. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
@@ -456,6 +461,14 @@ interface StepOptions<E extends Endpoint> {
     headers?: Lazy<Record<string, string>>;
     body?: Lazy<unknown>;
     timeoutMs?: number;
+    /**
+     * k6 export only — ignored by `journey run`. Overrides the slug used for this
+     * step's custom metrics when exporting with `--metrics-prefix <p>`: the step
+     * records Trend `<p>_<metric>_duration` and Counter `<p>_<metric>_tps`
+     * instead of names derived from the step name. `false` opts the step out of
+     * per-step metrics (it still counts toward `<p>_flow_duration`).
+     */
+    metric?: string | false;
     assert?: (res: HttpResponse<ResponseOf<E>>) => void | Promise<void>;
     after?: (res: HttpResponse<ResponseOf<E>>) => void | Promise<void>;
 }
@@ -715,4 +728,59 @@ type FetchResponse = Awaited<ReturnType<typeof globalThis.fetch>>;
  */
 declare function fetch$1(input: FetchInput, init?: FetchInit): Promise<FetchResponse>;
 
-export { AssertionError, type BuildRequestOptions, type CacheEntry, type CacheMode, type ConsoleLoggerOptions, DEFAULT_REQUEST_TIMEOUT_MS, DiskSubJourneyCache, type Endpoint, type EndpointDescriptor, type EndpointRef, type EntryJourneyOptions, type EnvValues, type Expectation, type GroupEndEvent, type GroupStartEvent, type HttpContext, type HttpMethod, type HttpResponse, type InvokeJourneyOptions, type JourneyConfig, JourneyConfigSchema, type JourneyDef, type JourneyHandle, type JourneyLogger, type JourneyOptions, type JourneyResult, type K6JourneyOptions, type LoadedConfig, type LogEvent, MemorySubJourneyCache, type PipelineNode, type PlannedNode, type RequestLog, type RequestSpec, type ResponseLog, type ResponseOf, type ReusableJourneyOptions, type RunEndEvent, type RunMeta, type RunPlannedEvent, type RunRecord, type RunStartEvent, type RunSummary, SECRET_HEADERS, type StepDef, type StepEndEvent, type StepOptions, type StepResult, type StepStartEvent, type SubJourneyCache, type SubJourneyCallDef, buildRequest, clearActiveEnvironment, clearRegistry, collectPipeline, collectSubPipeline, createConsoleLogger, createSubJourneyCache, describeError, env, execute, expect, fetch$1 as fetch, formatOpaqueBody, getCurrentCtx, getRegisteredJourneys, invokeJourney, isEndpointRef, isTextualContentType, journey, listEnvironments, listRuns, loadConfig, loadEnvironment, loggerFromEnv, maskHeaders, output, planJourney, pruneRuns, readRun, resolveBaseUrl, resolveConfigPaths, resolveUrl, runAllRegistered, runJourney, setActiveEnvironment, step, subJourneyCacheKey, tryEnv, writeRun };
+/**
+ * Reference to a file on disk, used as a request body (raw binary upload) or
+ * as a part of a `multipart()` body. Created by `fileFrom()`; the bytes are
+ * read lazily at request time by the Node runner, and at k6 init time (via
+ * `open(path, "b")`) by the k6 export.
+ */
+interface FileRef {
+    readonly __journeyFile: true;
+    /** Path as written in the journey — relative paths resolve against the project root. */
+    readonly path: string;
+    /** MIME type sent for the file. Defaults to `application/octet-stream`. */
+    readonly contentType?: string;
+    /** Filename reported in a multipart part. Defaults to the path's basename. */
+    readonly filename?: string;
+}
+/** A value accepted as one part of a `multipart()` body. */
+type MultipartValue = string | number | boolean | FileRef;
+/** A `multipart/form-data` request body. Created by `multipart()`. */
+interface MultipartBody {
+    readonly __journeyMultipart: true;
+    readonly parts: Readonly<Record<string, MultipartValue>>;
+}
+/**
+ * Reference a file to upload. Relative paths resolve against the **project
+ * root** (the directory holding `journey.config.json`), not the journey file.
+ *
+ * - As a step `body`, the file is sent as the raw request body with
+ *   `Content-Type: <contentType>` (default `application/octet-stream`).
+ * - As a `multipart()` part, it becomes a file part with `filename` (default:
+ *   the path's basename) and `contentType`.
+ *
+ * For `journey export k6`, the path should be a string literal so the export
+ * can pre-load it with `open(path, "b")` in the k6 init context.
+ *
+ * @example
+ * step("upload", {
+ *   endpoint: endpoints.virusScan,
+ *   body: () => multipart({ file: fileFrom("fixtures/sample.png", "image/png") }),
+ * });
+ */
+declare function fileFrom(path: string, contentType?: string, filename?: string): FileRef;
+/**
+ * Build a `multipart/form-data` body. String/number/boolean values become text
+ * fields; `fileFrom(...)` values become file parts. The runner (and k6) set
+ * the `Content-Type: multipart/form-data; boundary=…` header — any
+ * `Content-Type` supplied in the step's `headers` is dropped for multipart
+ * bodies, because a hand-written one can't carry the generated boundary.
+ *
+ * @example
+ * body: () => multipart({ description: "id card", file: fileFrom("fixtures/id.png", "image/png") })
+ */
+declare function multipart(parts: Record<string, MultipartValue>): MultipartBody;
+declare function isFileRef(value: unknown): value is FileRef;
+declare function isMultipartBody(value: unknown): value is MultipartBody;
+
+export { AssertionError, type BuildRequestOptions, type CacheEntry, type CacheMode, type ConsoleLoggerOptions, DEFAULT_REQUEST_TIMEOUT_MS, DiskSubJourneyCache, type Endpoint, type EndpointDescriptor, type EndpointRef, type EntryJourneyOptions, type EnvValues, type Expectation, type FileRef, type GroupEndEvent, type GroupStartEvent, type HttpContext, type HttpMethod, type HttpResponse, type InvokeJourneyOptions, type JourneyConfig, JourneyConfigSchema, type JourneyDef, type JourneyHandle, type JourneyLogger, type JourneyOptions, type JourneyResult, type K6JourneyOptions, type LoadedConfig, type LogEvent, MemorySubJourneyCache, type MultipartBody, type MultipartValue, type PipelineNode, type PlannedNode, type RequestLog, type RequestSpec, type ResponseLog, type ResponseOf, type ReusableJourneyOptions, type RunEndEvent, type RunMeta, type RunPlannedEvent, type RunRecord, type RunStartEvent, type RunSummary, SECRET_HEADERS, type StepDef, type StepEndEvent, type StepOptions, type StepResult, type StepStartEvent, type SubJourneyCache, type SubJourneyCallDef, buildRequest, clearActiveEnvironment, clearRegistry, collectPipeline, collectSubPipeline, createConsoleLogger, createSubJourneyCache, describeError, env, execute, expect, fetch$1 as fetch, fileFrom, formatOpaqueBody, getCurrentCtx, getRegisteredJourneys, invokeJourney, isEndpointRef, isFileRef, isMultipartBody, isTextualContentType, journey, listEnvironments, listRuns, loadConfig, loadEnvironment, loggerFromEnv, maskHeaders, multipart, output, planJourney, pruneRuns, readRun, resolveBaseUrl, resolveConfigPaths, resolveUrl, runAllRegistered, runJourney, setActiveEnvironment, step, subJourneyCacheKey, tryEnv, writeRun };

package/dist/index.js

@@ -398,6 +398,119 @@ function loggerFromEnv(env2 = process.env) {
   return void 0;
 }
 
+// src/body.ts
+import { randomBytes } from "crypto";
+import { readFile as readFile4 } from "fs/promises";
+import { basename, isAbsolute as isAbsolute2, resolve } from "path";
+function fileFrom(path, contentType, filename) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw new TypeError("fileFrom(path): path must be a non-empty string");
+  }
+  return {
+    __journeyFile: true,
+    path,
+    ...contentType !== void 0 ? { contentType } : {},
+    ...filename !== void 0 ? { filename } : {}
+  };
+}
+function multipart(parts) {
+  if (parts === null || typeof parts !== "object") {
+    throw new TypeError("multipart(parts): parts must be an object");
+  }
+  return { __journeyMultipart: true, parts: { ...parts } };
+}
+function isFileRef(value) {
+  return typeof value === "object" && value !== null && value.__journeyFile === true;
+}
+function isMultipartBody(value) {
+  return typeof value === "object" && value !== null && value.__journeyMultipart === true;
+}
+function isBinary(value) {
+  return value instanceof ArrayBuffer || ArrayBuffer.isView(value) || typeof Blob !== "undefined" && value instanceof Blob;
+}
+function defaultContentType(body) {
+  if (isMultipartBody(body)) return null;
+  if (isFileRef(body)) return body.contentType ?? "application/octet-stream";
+  if (isBinary(body)) {
+    if (typeof Blob !== "undefined" && body instanceof Blob && body.type) return body.type;
+    return "application/octet-stream";
+  }
+  return "application/json";
+}
+function filePath(ref, baseDir) {
+  return isAbsolute2(ref.path) ? ref.path : resolve(baseDir ?? process.cwd(), ref.path);
+}
+async function readFileRef(ref, baseDir) {
+  const abs = filePath(ref, baseDir);
+  try {
+    return await readFile4(abs);
+  } catch (err) {
+    throw new Error(
+      `fileFrom(${JSON.stringify(ref.path)}): cannot read ${abs}: ${err.message}`
+    );
+  }
+}
+function escapeDisposition(v) {
+  return v.replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/"/g, "%22");
+}
+async function encodeMultipart(body, baseDir) {
+  const boundary = `----JourneyBoundary${randomBytes(12).toString("hex")}`;
+  const chunks = [];
+  const text = (s) => chunks.push(Buffer.from(s, "utf8"));
+  for (const [name, value] of Object.entries(body.parts)) {
+    text(`--${boundary}\r
+`);
+    if (isFileRef(value)) {
+      const bytes = await readFileRef(value, baseDir);
+      const filename = value.filename ?? basename(value.path);
+      text(
+        `Content-Disposition: form-data; name="${escapeDisposition(name)}"; filename="${escapeDisposition(filename)}"\r
+Content-Type: ${value.contentType ?? "application/octet-stream"}\r
+\r
+`
+      );
+      chunks.push(bytes);
+      text("\r\n");
+    } else {
+      text(
+        `Content-Disposition: form-data; name="${escapeDisposition(name)}"\r
+\r
+${String(value)}\r
+`
+      );
+    }
+  }
+  text(`--${boundary}--\r
+`);
+  return {
+    body: Buffer.concat(chunks),
+    contentType: `multipart/form-data; boundary=${boundary}`
+  };
+}
+async function encodeBody(body, baseDir) {
+  if (typeof body === "string") return { body };
+  if (isMultipartBody(body)) return encodeMultipart(body, baseDir);
+  if (isFileRef(body)) return { body: await readFileRef(body, baseDir) };
+  if (typeof Blob !== "undefined" && body instanceof Blob) {
+    return { body: new Uint8Array(await body.arrayBuffer()) };
+  }
+  if (isBinary(body)) return { body };
+  return { body: JSON.stringify(body) };
+}
+function describeBodyForLog(body) {
+  const describeFile = (f) => `<file ${f.path}${f.contentType ? ` (${f.contentType})` : ""}>`;
+  if (isMultipartBody(body)) {
+    const parts = {};
+    for (const [k, v] of Object.entries(body.parts)) parts[k] = isFileRef(v) ? describeFile(v) : v;
+    return { "<multipart>": parts };
+  }
+  if (isFileRef(body)) return describeFile(body);
+  if (body instanceof ArrayBuffer) return `<binary ${body.byteLength} bytes>`;
+  if (ArrayBuffer.isView(body)) return `<binary ${body.byteLength} bytes>`;
+  if (typeof Blob !== "undefined" && body instanceof Blob) return `<binary ${body.size} bytes>`;
+  return body;
+}
+
 // src/http.ts
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 function resolveUrl(endpoint, ctx, params, query) {
@@ -439,8 +552,15 @@ function buildRequest(opts, ctx) {
     ...opts.headers ?? {}
   };
   const hasBody = opts.body !== void 0;
-  if (hasBody && !("content-type" in lower(headers))) {
-    headers["Content-Type"] = "application/json";
+  if (hasBody) {
+    const contentType = defaultContentType(opts.body);
+    if (contentType === null) {
+      for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === "content-type") delete headers[k];
+      }
+    } else if (!("content-type" in lower(headers))) {
+      headers["Content-Type"] = contentType;
+    }
   }
   const spec = { method: opts.endpoint.method, url, headers };
   if (hasBody) spec.body = opts.body;
@@ -458,13 +578,23 @@ async function execute(req, ctx) {
     method: req.method,
     url: req.url,
     headers: req.headers,
-    ...req.body !== void 0 ? { body: req.body } : {}
+    ...req.body !== void 0 ? { body: describeBodyForLog(req.body) } : {}
   };
   ctx.logger?.onRequest?.(logReq);
   const f = ctx.fetchImpl ?? fetch;
   const init = { method: req.method, headers: req.headers };
   if (req.body !== void 0) {
-    init.body = typeof req.body === "string" ? req.body : JSON.stringify(req.body);
+    let encoded;
+    try {
+      encoded = await encodeBody(req.body, ctx.baseDir);
+    } catch (err) {
+      ctx.logger?.onError?.(logReq, err, 0);
+      throw err;
+    }
+    init.body = encoded.body;
+    if (encoded.contentType !== void 0) {
+      init.headers = { ...req.headers, "Content-Type": encoded.contentType };
+    }
   }
   if (ctx.dispatcher !== void 0) {
     init.dispatcher = ctx.dispatcher;
@@ -501,7 +631,7 @@ async function execute(req, ctx) {
 
 // src/cache.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir2, readFile as readFile4, rm, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile5, rm, writeFile as writeFile2 } from "fs/promises";
 import { join as join4 } from "path";
 function subJourneyCacheKey(journeyName, resolvedKey) {
   return `${journeyName}:${resolvedKey}`;
@@ -542,7 +672,7 @@ var DiskSubJourneyCache = class {
     const path = this.pathFor(key);
     let raw;
     try {
-      raw = await readFile4(path, "utf8");
+      raw = await readFile5(path, "utf8");
     } catch {
       return void 0;
     }
@@ -1215,11 +1345,14 @@ export {
   execute,
   expect,
   fetch2 as fetch,
+  fileFrom,
   formatOpaqueBody,
   getCurrentCtx,
   getRegisteredJourneys,
   invokeJourney,
   isEndpointRef,
+  isFileRef,
+  isMultipartBody,
   isTextualContentType,
   journey,
   listEnvironments,
@@ -1228,6 +1361,7 @@ export {
   loadEnvironment,
   loggerFromEnv,
   maskHeaders,
+  multipart,
   output,
   planJourney,
   pruneRuns,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usejourney/core",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",