Feature request: Expose existing IdempotencyRecord in IdempotencyValidationError

[kevin-secrist]

Use case

In my current work I'm reusing the Idempotency package to consolidate potentially many events into one final entity. The first event needs to create the entity, and following events should be updates to that existing entity. The function that has been made idempotent returns the ID of the entity that was created. When the package throws a IdempotencyValidationError that is enough for me to trigger an update but it would also be nice to know the entity ID.

For example

try {
  const createdEntityId = await createThingIdempotent(createRequest)
  return createdEntityId
} catch (error) {
  if (error instanceof IdempotencyValidationError) {
    await handleTheUpdateCase() // example
    // we don't have the entityId here to return
    return -1
  }
  throw error
}

I have means of looking up what the entityId is by searching/listing resources, so this is not a blocker for me but having the existing record available seems like a reasonable thing to expect in this kind of workflow. If the payload failing validation is an exceptional scenario, ideally you'd want to be able to recover from it rather than fail outright. In order to recover, I expect you may want to know what data is in conflict.

Solution/User Experience

Simply exposing the IdempotencyRecord or at least the responseData in a similar fashion to how it is done with IdempotencyItemAlreadyExistsError should be enough to accomplish this.

powertools-lambda-typescript/packages/idempotency/src/errors.ts

Lines 6 to 13 in f9b7e6c

	class IdempotencyItemAlreadyExistsError extends Error {
	public existingRecord?: IdempotencyRecord;
	public constructor(message?: string, existingRecord?: IdempotencyRecord) {
	super(message);
	this.existingRecord = existingRecord;
	}
	}

powertools-lambda-typescript/packages/idempotency/src/persistence/BasePersistenceLayer.ts

Lines 156 to 161 in f9b7e6c

	if (this.getFromCache(idempotencyRecord.idempotencyKey)) {
	throw new IdempotencyItemAlreadyExistsError(
	`Failed to put record for already existing idempotency key: ${idempotencyRecord.idempotencyKey}`,
	idempotencyRecord
	);
	}

At the place where this error is currently thrown, the existing record is in scope and should be easy to include.

powertools-lambda-typescript/packages/idempotency/src/persistence/BasePersistenceLayer.ts

Lines 317 to 326 in f9b7e6c

	private validatePayload(data: JSONValue, record: IdempotencyRecord): void {
	if (this.payloadValidationEnabled) {
	const hashedPayload: string = this.getHashedPayload(data);
	if (hashedPayload !== record.payloadHash) {
	throw new IdempotencyValidationError(
	'Payload does not match stored record for this event key'
	);
	}
	}
	}

Alternative solutions

No response

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[am29d]

Hey @kevin-secrist ,

thank for raising the issue. We could return the record in the error, since we have it in the scope anyway, similar to IdempotencyItemAlreadyExistsError. I am not sure how you can recover from arbitrary validation errors during runtime, unless you have a very narrow use case, where you know exactly what could go wrong and how to recover.

We see many requests that lead to extending the idempotency with a hook, something where customer can attach their own logic in case of idempotency errors, i.e. collect metrics, redact and log specific information, or recover from validation errors. I can see that your use cases would also fit great into this area.

For now, I see no issues to return IdempotencyRecord inside the IdempotencyValidationError.