Skip to content

Conversation

@confused-Techie
Copy link
Member

@confused-Techie confused-Techie commented Nov 25, 2025

This PR introduces a few things, but with a main focus on the Server-Timing Specification.

The Server-Timing specification can allow us much greater and simple insight into the performance and behavior of the backend without having to invest in complicated analytics or greatly increased logging. It lets us at a glance see how long certain tasks take so that we can later attempt to optimize them or identify problems in them.

You'll notice to do this I had to make a few other changes:

node.version

Each controller has a standard object schema that allows dynamic ExpressJS route building, dynamic Swagger UI documentation updates, and reduces boilerplate needed for definitions. But the changes in this PR change the positional parameters provided to the main logic function, so instead of updating every single controller like I've done in the past, I opted to instead to define a version key on the node which allows us to handle it differently in the dynamic portion of the ExpressJS route builder, meaning we can update bit by bit instead of all at once.

New Context Object

Because I also wanted to take this chance to stop having to define new instances of CallStack and the new Timecop class, we also have a new context object for v2 Nodes that handles the creation of these common classes automatically. It also bundles the req, res and params objects into it, which allows us to call the logic function with a single positional parameter.


I do want to mention that these new changes will also be the backbone of other cool future plans:

  • Support and Adopt "Problem Details" specification #292 can be more easily implemented by allowing us to do content negotiation before giving the return object to the ExpressJS route handler
  • We can begin grouping logs by the transaction ID by wrapping our logging utility in a class that depends on information from the req object

Now lets talk about some of the downsides:

Something I fear will need to be done when recreating the contract between a controller and the main app, which has been a problem in this codebase since forever, is we will need to re-write the tests for this. I think this time around our best bet is to rely much more heavily on HTTP based tests, we already do this in some capacity, but realistically since HTTP is our only service contract that should be our priority in tests, while still attempting to test the smaller components when possible.


One last important note, I've only added Server-Timing for a single endpoint, since adding it on each endpoint is relatively small I hope to do it while working on other sections of the code, but this PR contains the bulk of the initial setup needed for this to work at all

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants