🕵️ strengthen error propagation + add tests (#23)

This change adds the following features:
* ability to get either an `ArrayBuffer` or a `Uint8Array` response for developer ease
* `ProdiaCapacityError` gives a more descriptive error asking you to check your token & job type
* `ProdiaBadResponseError` shows the raw response text to give you more information e.g. "invalid token"
* last item in state history is checked for failure error messages

This change adds the following tests:

* a bad job config must return a `ProdiaUserError` referencing that the json schema validation failed, the name of the field, and the criteria for it's failure (i.e. beyond a maximum)
* a bad job type returns a `ProdiaCapacityError`. we plan on changing this in the future but the current correct response is a 429 `ProdiaCapacityError`
* a bad token must return a `ProdiaBadResponseError` referencing "invalid token"
* `image/png` accept type must return a real png image

Author: montyanderson

.github/workflows/validate.yml

@@ -11,12 +11,14 @@ jobs:
 
             - uses: denoland/setup-deno@v1
               with:
-                  deno-version: vx.x.x
+                  deno-version: v2.x.x
 
             - run: deno fmt --check
 
             - run: deno check prodia.ts
 
+            - run: deno check v2/index.ts
+
             - run: deno test --allow-env --allow-net
               env:
                   PRODIA_TOKEN: ${{ secrets.PRODIA_TOKEN }}

test/v2.errors.test.ts

@@ -0,0 +1,98 @@
+import { assert, assertStringIncludes } from "jsr:@std/assert";
+import {
+	createProdia,
+	ProdiaBadResponseError,
+	ProdiaCapacityError,
+	ProdiaUserError,
+} from "../v2/index.ts";
+
+const token = Deno.env.get("PRODIA_TOKEN");
+
+if (typeof token !== "string") {
+	throw new Error("PRODIA_TOKEN is not set");
+}
+
+await Deno.test("Error Propagation: Bad Job Config returns ProdiaUserError", {
+	sanitizeResources: false,
+}, async () => {
+	const client = createProdia({
+		token,
+	});
+
+	try {
+		const job = await client.job({
+			type: "inference.flux.schnell.txt2img.v1",
+			config: {
+				prompt: "puppies in a cloud, 4k",
+				steps: 1000,
+			},
+		});
+
+		throw new Error("Job should not succeed");
+	} catch (err) {
+		assert(
+			err instanceof ProdiaUserError,
+			"Error should be a ProdiaUserError",
+		);
+		assertStringIncludes(err.message, "jsonschema validation failed");
+		assertStringIncludes(err.message, "steps/maximum");
+		assertStringIncludes(err.message, "maximum: got 1,000");
+	}
+});
+
+await Deno.test("Error Propagation: No Job Type returns ProdiaCapacityError", {
+	sanitizeResources: false,
+}, async () => {
+	const client = createProdia({
+		token,
+		maxRetries: 2,
+	});
+
+	try {
+		await client.job({
+			config: {
+				prompt: "puppies in a cloud, 4k",
+			},
+		});
+
+		throw new Error("Job should not succeed");
+	} catch (err) {
+		assert(
+			err instanceof ProdiaCapacityError,
+			"Error should be a ProdiaCapacityError",
+		);
+
+		assertStringIncludes(
+			err.message,
+			"Are your sure your token and job type are correct?",
+		);
+	}
+});
+
+await Deno.test(
+	'Error Propagation: Bad Token returns ProdiaBadResponseError "invalid token"',
+	{ sanitizeResources: false },
+	async () => {
+		const client = createProdia({
+			token: "bad-token-xxx",
+		});
+
+		try {
+			await client.job({
+				type: "inference.flux.schnell.txt2img.v1",
+				config: {
+					prompt: "puppies in a cloud, 4k",
+				},
+			});
+
+			throw new Error("Job should not succeed");
+		} catch (err) {
+			assert(
+				err instanceof ProdiaBadResponseError,
+				"Error should be a ProdiaBadResponseError",
+			);
+
+			assertStringIncludes(err.message, "401 token is invalid");
+		}
+	},
+);

test/v2.examples.test.ts

@@ -0,0 +1,88 @@
+import { assert, assertEquals } from "jsr:@std/assert";
+import { createProdia } from "../v2/index.ts";
+
+const token = Deno.env.get("PRODIA_TOKEN");
+
+if (typeof token !== "string") {
+	throw new Error("PRODIA_TOKEN is not set");
+}
+
+const isJpeg = (image: ArrayBuffer): boolean => {
+	const view = new Uint8Array(image);
+
+	return view[0] === 0xff && view[1] === 0xd8;
+};
+
+const isPng = (image: ArrayBuffer): boolean => {
+	const view = new Uint8Array(image);
+
+	return [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A].every((byte, i) =>
+		byte === view[i]
+	);
+};
+
+await Deno.test("Example Job: JPEG Output (ArrayBuffer)", async () => {
+	const client = createProdia({
+		token,
+	});
+
+	const job = await client.job({
+		type: "inference.flux.schnell.txt2img.v1",
+		config: {
+			prompt: "puppies in a cloud, 4k",
+			steps: 1,
+			width: 1024,
+			height: 1024,
+		},
+	});
+
+	const image = await job.arrayBuffer();
+
+	assert(image instanceof ArrayBuffer, "Image should be an ArrayBuffer");
+	assert(!(image instanceof Uint8Array), "Image should not be a Uint8Array");
+	assertEquals(isJpeg(image), true, "Image should be a JPEG");
+});
+
+await Deno.test("Example Job: JPEG Output (Uint8Array)", async () => {
+	const client = createProdia({
+		token,
+	});
+
+	const job = await client.job({
+		type: "inference.flux.schnell.txt2img.v1",
+		config: {
+			prompt: "puppies in a cloud, 4k",
+			steps: 1,
+			width: 1024,
+			height: 1024,
+		},
+	});
+
+	const image = await job.uint8Array();
+
+	assert(image instanceof Uint8Array, "Image should be a Uint8Array");
+	assertEquals(isJpeg(image), true, "Image should be a JPEG");
+});
+
+await Deno.test("Example Job: PNG Output (Uint8Array)", async () => {
+	const client = createProdia({
+		token,
+	});
+
+	const job = await client.job({
+		type: "inference.flux.schnell.txt2img.v1",
+		config: {
+			prompt: "puppies in a cloud, 4k",
+			steps: 1,
+			width: 1024,
+			height: 1024,
+		},
+	}, {
+		accept: "image/png",
+	});
+
+	const image = await job.uint8Array();
+
+	assert(image instanceof Uint8Array, "Image should be a Uint8Array");
+	assertEquals(isPng(image), true, "Image should be a PNG");
+});

test/v2.test.ts

@@ -44,9 +44,10 @@ const defaultJobOptions: ProdiaJobOptions = {
 export type ProdiaJobResponse = {
 	job: ProdiaJob;
 
-	// Currently only one output field is expected for all job types.
-	//This will return the raw bytes for that output.
+	// currently these are the only output field for all job types.
+	// they will return the raw bytes for that output.
 	arrayBuffer: () => Promise<ArrayBuffer>;
+	uint8Array: () => Promise<Uint8Array>;
 };
 
 /* client & client configuration*/
@@ -75,7 +76,7 @@ export const createProdia = ({
 	token,
 	baseUrl = "https://inference.prodia.com/v2",
 	maxErrors = 1,
-	maxRetries = Infinity,
+	maxRetries = 10,
 }: CreateProdiaOptions): Prodia => {
 	const job = async (
 		params: ProdiaJob,
@@ -164,7 +165,7 @@ export const createProdia = ({
 
 		if (response.status === 429) {
 			throw new ProdiaCapacityError(
-				"Unable to schedule the job with current token.",
+				"Unable to schedule the job. Are your sure your token and job type are correct?",
 			);
 		}
 
@@ -175,30 +176,41 @@ export const createProdia = ({
 				throw new ProdiaUserError(body.error);
 			}
 
+			const lastStateHistory = body.state.history.slice(-1)[0];
+
+			if (lastStateHistory && "message" in lastStateHistory) {
+				throw new ProdiaUserError(lastStateHistory.message);
+			}
+
 			throw new Error("Job Failed: Bad Content-Type: application/json");
 		}
 
+		if (response.status < 200 || response.status > 299) {
+			throw new ProdiaBadResponseError(
+				`${response.status} ${await response.text()}`,
+			);
+		}
+
 		const body = await response.formData();
+
 		const job = JSON.parse(
 			new TextDecoder().decode(
 				await (body.get("job") as Blob).arrayBuffer(),
 			),
 		) as ProdiaJob;
+
 		if ("error" in job && typeof job.error === "string") {
 			throw new ProdiaUserError(job.error);
 		}
 
-		if (response.status < 200 || response.status > 299) {
-			throw new ProdiaBadResponseError(
-				`${response.status} ${response.statusText}`,
-			);
-		}
-
-		const buffer = await (body.get("output") as Blob).arrayBuffer();
-
 		return {
 			job: job,
-			arrayBuffer: () => Promise.resolve(buffer),
+			arrayBuffer: async () =>
+				await (body.get("output") as Blob).arrayBuffer(),
+			uint8Array: async () =>
+				new Uint8Array(
+					await (body.get("output") as Blob).arrayBuffer(),
+				),
 		};
 	};