CSCfi / CSCfi/rems

Error schema for commands

Open
#3,487 0 comments 0 reactions 0 assignees View on GitHub
Technical Debt
Dominant language
Clojure
Stars
66
Forks
28
Avg merge
7d 4h
Merged PRs (30d)
2

Description

There is currently no schema for errors returned by commands. There seems to have been a convention to pass a translation key with `:args` that get replaced into the tokenized error message `%1`, `%some-arg%` etc, and outside that, errors are handled case by case in the frontend. This seems to have been working reasonably well until the introduction of catalogue item hierarchy, which presents an additional dimension of things that need to be communicated to the user, such as the `user` you've invited hasn't got entitlement to the resource `x`, therefore you cannot change the applications resource to include `x`'s complementary items `y, z, ...`. Some commands return an error with the key `catalogue-item-id`, others use `catalogue-item-ids`, and there's `:catalogue-item/id` in other responses as well. Other examples forthcoming.

This creates unnecessary coupling between the backend and the frontend as the frontend needs to be aware of the actual error types and what domain entities they might also include (and how the key is spelled in this instance) while there's no schema to guarantee their presence, which makes changing the errors kind of fragile and invites developer errors in the long run as we aren't alerted to breaking the assumed contract between the call site and the command, unless there's a browser test that checks for the entire error string with also the exact IDs or whichever datum is displayed.

There should be a generic construct for an error message so that we don't have to invent them on the fly as they get more complex. A schema could be validated and checked against in development time, and it would potentially help API consumers as well. Perhaps it could also lay some first steps towards using structured logging such as [μ/log](https://github.com/BrunoBonacci/mulog) or [telemere](https://github.com/taoensso/telemere) in the future.

For reference
https://www.rfc-editor.org/rfc/rfc9457.html

Contributor guide

Open the contributing guide

Research direction

The issue names no files, tests, or entry points. Start by tracing command error responses and the frontend handling of their translation keys and entity fields, then inventory the inconsistent error shapes. Done should include an agreed generic error schema, development-time validation, and coverage of the catalogue-item examples described here.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.