refuse loop counts that don't fit the format

Author: matmen

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.20.2
+
+### Fixes
+
+- Loop counts that don't fit the file format are refused with a `RangeError` naming the format's largest count, instead of wrapping around: a GIF with `loopCount: 65536` was written with 0, which plays forever (GIF and animated WebP store up to 65535 and 65534, APNG up to 2147483646). This applies to `encodeGIF()`, `encodeWebP()` and `encodeAPNG()` of animations and to the streaming encoders.
+
 ## 3.20.1
 
 ### Performance

src/animation-encoder.ts

@@ -6,7 +6,7 @@ import { Frame, FrameOptions } from './frame.ts';
 import { Optimizer, Compositor, InputFrame, OptimizeOptions, OptimizedFrame, coverCanvas, fillUnchanged } from './util/optimize.ts';
 import { compressAsync, decompressAsync } from './codecs/zlib.ts';
 import { resolveMetadata, pngText, exifData, gifComments } from './metadata.ts';
-import { finite, compressionLevel } from './util/options.ts';
+import { finite, compressionLevel, fitLoops } from './util/options.ts';
 import type { AnimationOptions, AnimationEncodeOptions, WebPAnimationEncodeOptions, GIFEncodeOptions, APNGEncodeOptions } from './animation.ts';
 
 // (ImageScript, like GIF, counts repetitions: -1 forever, 0 play once; APNG and WebP count plays, 0 forever)
@@ -134,6 +134,7 @@ export class AnimationEncoder {
     /** @internal */
     static __webp__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, quality, effort = 2, sharpYuv = false, alphaQuality = 100 }: WebPAnimationEncodeOptions & AnimationOptions): AnimationEncoder {
         canvas(width, height, loopCount);
+        fitLoops(loopCount, 'WebP');
         if (width > 1 << 24 || height > 1 << 24) throw new RangeError('WebP: canvas too large');
         const lossy = webp.lossyOptions(quality, effort, sharpYuv, alphaQuality);
         const resolved = resolveMetadata(metadata), chunks: Uint8Array[] = [];
@@ -164,6 +165,7 @@ export class AnimationEncoder {
     static __gif__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, quality: qualityOption = 95 }: GIFEncodeOptions & AnimationOptions): AnimationEncoder {
         const quality = finite(qualityOption, 'quality');
         canvas(width, height, loopCount);
+        fitLoops(loopCount, 'GIF');
         const comments = gifComments(resolveMetadata(metadata));
         // (the first frame is encoded last: it needs a transparent index if any frame restores the background)
         let first: gifCodec.GIFFrame | null = null, restores = false;
@@ -191,6 +193,7 @@ export class AnimationEncoder {
     static __apng__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, compression: compressionOption = 4 }: APNGEncodeOptions & AnimationOptions): AnimationEncoder {
         const compression = compressionLevel(compressionOption);
         canvas(width, height, loopCount);
+        fitLoops(loopCount, 'APNG');
         const text = pngText(resolveMetadata(metadata));
         // the frames are kept compressed (quickly): the pixel format, and whether opaque animations are stored without
         // transparency, depend on all of them; then they are converted and compressed one at a time, like encodeAPNG

src/animation.ts

@@ -12,7 +12,7 @@ import { Frame, FrameDisposalModes } from './frame.ts';
 import { ImageType } from './image-type.ts';
 import { optimize, OptimizeOptions, OptimizedFrame } from './util/optimize.ts';
 import { Metadata, resolveMetadata, pngText, exifData, gifComments } from './metadata.ts';
-import { isOptions, finite, compressionLevel } from './util/options.ts';
+import { isOptions, finite, compressionLevel, fitLoops } from './util/options.ts';
 import { MAX_PIXELS, decoding } from './util/limits.ts';
 import { AnimationEncoder } from './animation-encoder.ts';
 
@@ -297,6 +297,7 @@ export class Animation extends Array<Frame> {
     encodeGIF(quality?: number): Promise<Uint8Array>;
     async encodeGIF(qualityOrOptions: number | GIFEncodeOptions = 95): Promise<Uint8Array> {
         const { quality = 95, metadata = {}, optimize = true } = isOptions(qualityOrOptions) ? qualityOrOptions : { quality: qualityOrOptions };
+        fitLoops(this.loopCount, 'GIF');
         this.__validate__();
         const frames = optimize
             ? this.__optimized__({ replace: false, even: false, alpha: 'frame', palette: 256, cover: true }).map(f => ({ ...f, dispose: f.dispose ? 3 : 1 }))
@@ -334,6 +335,7 @@ export class Animation extends Array<Frame> {
     encodeAPNG(compression?: number): Promise<Uint8Array>;
     async encodeAPNG(compressionOrOptions: number | APNGEncodeOptions = 4): Promise<Uint8Array> {
         const { compression = 4, metadata = {}, optimize = true } = isOptions(compressionOrOptions) ? compressionOrOptions : { compression: compressionOrOptions };
+        fitLoops(this.loopCount, 'APNG');
         this.__validate__();
         if (!this.length) throw new Error('An animation needs at least one frame');
 
@@ -350,6 +352,7 @@ export class Animation extends Array<Frame> {
      * @param options See {@link WebPAnimationEncodeOptions}
      */
     async encodeWebP({ metadata = {}, optimize = true, quality, effort = 2, sharpYuv = false, alphaQuality = 100 }: WebPAnimationEncodeOptions = {}): Promise<Uint8Array> {
+        fitLoops(this.loopCount, 'WebP');
         this.__validate__();
         if (!this.length) throw new Error('An animation needs at least one frame');
         const lossy = webp.lossyOptions(quality, effort, sharpYuv, alphaQuality);

src/util/options.ts

@@ -31,3 +31,17 @@ export const compressionLevel = (value: number): number => Math.min(9, Math.max(
 
 /** A color argument: a finite number (as RGBA, 0xrrggbbaa) */
 export const color = (value: number, name = 'color'): number => finite(value, name);
+
+// the largest finite loop count each format stores: GIF 16 bits of repeats, WebP 16 bits of plays (count + 1), APNG 31
+// bits of plays
+const LOOP_LIMITS = { GIF: 65535, WebP: 65534, APNG: 2 ** 31 - 2 };
+
+/**
+ * Checks that a finite loop count fits the format's field (a larger one used to wrap around, e.g. to 0, which plays
+ * forever): throws a RangeError naming the format's largest count. Forever (-1 or Infinity) always fits
+ */
+export function fitLoops(loopCount: number, format: keyof typeof LOOP_LIMITS): number {
+    if (loopCount !== Infinity && loopCount > LOOP_LIMITS[format])
+        throw new RangeError(`${format} stores loop counts up to ${LOOP_LIMITS[format]} (or Infinity to loop forever), not ${loopCount}`);
+    return loopCount;
+}

tests/loop-limits.js

@@ -0,0 +1,40 @@
+const {Animation, Frame} = require('..');
+
+const panic = message => {
+	console.error(message);
+	process.exit(1);
+};
+
+// loop counts are stored in fixed-size fields: a count that doesn't fit used to wrap around (65536 repeats became 0, which
+// plays forever), now it's refused; the largest count of each format round trips
+(async () => {
+	const frames = () => [0xff0000ff, 0x00ff00ff].map(color => Frame.from(new Animation([new Frame(4, 4)])[0].fill(color), {duration: 50}));
+	const limits = {GIF: 65535, WebP: 65534, APNG: 2 ** 31 - 2};
+	const encode = {GIF: a => a.encodeGIF(), WebP: a => a.encodeWebP(), APNG: a => a.encodeAPNG()};
+	const factory = {GIF: Animation.gifEncoder, WebP: Animation.webpEncoder, APNG: Animation.apngEncoder};
+
+	for (const [format, max] of Object.entries(limits)) {
+		const decoded = await Animation.decode(await encode[format](new Animation(frames(), {loopCount: max})));
+		if (decoded.loopCount !== max) panic(`${format}: loop count ${max} read back as ${decoded.loopCount}`);
+		for (const forever of [-1, Infinity]) {
+			const again = await Animation.decode(await encode[format](new Animation(frames(), {loopCount: forever})));
+			if (again.loopCount !== -1 && again.loopCount !== Infinity) panic(`${format}: loop count ${forever} read back as ${again.loopCount}`);
+		}
+
+		for (const count of [max + 1, max + 1000, 2 ** 40]) {
+			let error = null;
+			try { await encode[format](new Animation(frames(), {loopCount: count})); } catch (e) { error = e; }
+			if (!(error instanceof RangeError) || !error.message.includes(String(max))) panic(`${format}: loop count ${count} should be refused with the largest count, got ${error}`);
+
+			error = null;
+			try { factory[format].call(Animation, 4, 4, {loopCount: count}); } catch (e) { error = e; }
+			if (!(error instanceof RangeError)) panic(`${format} encoder: loop count ${count} should be refused, got ${error}`);
+		}
+
+		// the streaming encoder writes the same count
+		const encoder = factory[format].call(Animation, 4, 4, {loopCount: max});
+		for (const frame of frames()) await encoder.add(frame);
+		const streamed = await Animation.decode(await encoder.finish());
+		if (streamed.loopCount !== max) panic(`${format} encoder: loop count ${max} read back as ${streamed.loopCount}`);
+	}
+})().catch(error => panic(error.stack || String(error)));