Add customUpCodes support for HTTP monitors (Backend) by harsh-aghara · Pull Request #3690 · bluewave-labs/Checkmate

harsh-aghara · 2026-05-31T18:49:31Z

Describe your changes

This PR adds backend support for a customUpCodes field to HTTP monitors. This feature allows users to specify which non-2xx HTTP status codes (e.g., 401 Unauthorized, 301 Moved Permanently) should be treated as a successful "UP" status instead of the default "DOWN".

Key Changes:

Schema & Types: Added customUpCodes: number[] to the Mongoose Monitor schema and TypeScript types, defaulting to [].
Validation: Updated Zod schemas in monitorValidation.ts to validate the new field on monitor creation and updates.
Core Logic: Modified HttpProvider to check customUpCodes during both success paths and error paths (when got throws an HTTPError).
Geo Checks: Updated GlobalPingService and geoChecksService to ensure geographically distributed HTTP checks also respect the custom status codes.
Testing: Added an exhaustive unit test suite in httpProvider.test.ts to cover error scenarios, success overrides, empty arrays, and matcher precedence.

Write your issue number after "Fixes "

Refs #3657

Please ensure all items are checked off before requesting a review. "Checked off" means you need to add an "x" character between brackets so they turn into checkmarks.

Adds a customUpCodes field to the monitor schema to allow users to specify which HTTP status codes should be treated as UP instead of DOWN. Includes core logic in HttpProvider and unit tests. Refs bluewave-labs#3657

ajhollid

I haven't had a chance to do a full review yet, but off the bat this should use the http codes defined in the http library, these should not be arbitrary or self defined numbers.

The http library already properly defines the codes and should be used for type discrimination.

https://nodejs.org/api/http.html#httpstatus_codes

Addresses reviewer feedback by enforcing strict validation on the array. Previously, the Zod schema accepted any arbitrary number, which could allow invalid or self-defined HTTP codes (e.g., 5000) to be saved to the database. Refs bluewave-labs#3657

harsh-aghara · 2026-06-01T08:03:23Z

I haven't had a chance to do a full review yet, but off the bat this should use the http codes defined in the http library, these should not be arbitrary or self defined numbers.

The http library already properly defines the codes and should be used for type discrimination.

https://nodejs.org/api/http.html#httpstatus_codes

@ajhollid I just pushed a commit that updates the Zod schemas to validate customUpCodes directly against http.STATUS_CODES. It now uses the http library for discrimination and will reject any fake or arbitrary numbers (like 9999) from being saved. I also added full unit tests for this behavior.

Br0wnHammer

Overall, the PR looks solid and clean. I have one concern:
got follows redirects by default, so a 301/302 never shows up as the final status; the redirect target's code does. That means adding 3xx codes to `customUpCodes' won't actually work here (the 301 test only passes because the response is mocked). Should 3xx be supported, or should we drop the 301 example?

ajhollid

This needs a bit more work, please see my comments in the review.

Thanks!

ajhollid · 2026-06-03T16:32:04Z

 	uptimePercentage?: number;
 	notifications: string[];
 	tags: string[];
+	customUpCodes: number[];


Let's properly define an HttpStatusCode type and a set we can use to verify

export const HttpStatusCodes = Object.keys(http.STATUS_CODES).map(Number); export const HttpStatusCodeSet = new Set(HttpStatusCodes); export type HttpStatusCode = number;

and use it here to properly type this:

customUpCodes: HttpStatusCode[];

ajhollid · 2026-06-03T16:32:51Z

 import { DnsRecordTypes, MonitorMatchMethods, MonitorStatuses, MonitorTypes, PageSpeedStrategies } from "@/types/monitor.js";
+import http from "node:http";
+
+const httpStatusCode = z.number().refine((code) => code.toString() in http.STATUS_CODES, { message: "Must be a valid HTTP status code" });


This can now be simplified

const httpStatusCode = z.number().refine((code) => HttpStatusCodeSet.has(code), { message: "Must be a valid HTTP status code" });

simplified this, thanks for the review!

ajhollid · 2026-06-03T16:38:15Z


 	private handleHttpError<T>(error: unknown, monitor: Monitor): MonitorStatusResponse<T> {
 		if (error instanceof HTTPError || error instanceof RequestError) {
+			const isCustomUp = error instanceof HTTPError && (monitor.customUpCodes ?? []).includes(error.response?.statusCode);


This is very hard to read and has a superfluous instance assertion. Why not do something like the following:

const statusCode = error.response?.statusCode; const statusUp = statusCode !== undefined && monitor.customUpCodes.includes(statusCode); ... return { monitorId: monitor.id, teamId: monitor.teamId, type: monitor.type, status: statusUp, code: statusCode ?? NETWORK_ERROR, message: error.message, responseTime: error.timings?.phases?.total ?? 0, timings: error.timings, payload: null as T, };

Something along those lines is clearer and much easier to read.

Done.
broke down code into more readable parts.

ajhollid · 2026-06-03T16:39:29Z

 				teamId: monitor.teamId,
 				type: monitor.type,
-				status: response.ok && matchResult.ok,
+				status: ((monitor.customUpCodes ?? []).includes(response.statusCode) || response.ok) && matchResult.ok,


This difficult to read line then simply becomes

status: statusUp && matchResult.ok,

It's also worth noting that this is acutally not needed since got throws on non 2xx responses.

This is harmless though and we can leave it in in case we decide to change the got default behaviour.

ajhollid · 2026-06-03T16:39:56Z

 	}

-	async pollForResults(measurementId: string, timeoutMs: number = MAX_POLL_TIMEOUT_MS): Promise<GeoCheckResult[]> {
+	async pollForResults(measurementId: string, timeoutMs: number = MAX_POLL_TIMEOUT_MS, customUpCodes: number[] = []): Promise<GeoCheckResult[]> {


Correct type can be used here

Done.
Updated globalPingService.ts to use correct type.

harsh-aghara · 2026-06-03T16:48:28Z

Overall, the PR looks solid and clean. I have one concern:
got follows redirects by default, so a 301/302 never shows up as the final status; the redirect target's code does. That means adding 3xx codes to `customUpCodes' won't actually work here (the 301 test only passes because the response is mocked). Should 3xx be supported, or should we drop the 301 example?

@Br0wnHammer Good catch, you are right. Since got follows redirects by default, it will return the final status code instead of the 3xx code in production.

To handle this, I see two options:

Restrict 3xx codes: We can update the Zod validation to reject 3xx codes so users don't get confused (and remove the 301 test example).
Set followRedirect: false: We can configure got to stop following redirects. However, this creates a new issue: if the final destination service is actually down, the monitor will still report as "Up" just because it received the initial 3xx response.

I think Option 1 is the safer choice.
What are your thoughts on this @ajhollid ?

Add HttpStatusCode types and simplify provider logic

ajhollid · 2026-06-03T19:03:11Z

Overall, the PR looks solid and clean. I have one concern:
got follows redirects by default, so a 301/302 never shows up as the final status; the redirect target's code does. That means adding 3xx codes to `customUpCodes' won't actually work here (the 301 test only passes because the response is mocked). Should 3xx be supported, or should we drop the 301 example?

@Br0wnHammer Good catch, you are right. Since got follows redirects by default, it will return the final status code instead of the 3xx code in production.

To handle this, I see two options:

Restrict 3xx codes: We can update the Zod validation to reject 3xx codes so users don't get confused (and remove the 301 test example).

Set followRedirect: false: We can configure got to stop following redirects. However, this creates a new issue: if the final destination service is actually down, the monitor will still report as "Up" just because it received the initial 3xx response.

I think Option 1 is the safer choice. What are your thoughts on this @ajhollid ?

Thanks for making changes here, this is looking good 🚀

I think the issue around redirects isn't straightforward, especially since I don't know how the geo checks handle redirects.

Additionally, got's responseok value is depends on the config, ie if followRedirect is turned on or off.

What about extracting a utility to deal with status that is independent of got's response.ok, instead just returning a value based purely on status codes?

export const isStatusUp = (statusCode, customUpCodes) => {
   return statusCode >= 200 && statusCode < 300 || customUpCodes.includes(statusCode)
}

something like that, which we can use in both the HttpProvider and globalPing provider to ensure consistent values?

…ok and modified utils test accordingly

harsh-aghara · 2026-06-04T17:17:00Z

@ajhollid I've implemented the isStatusUp utility as requested, so the UP status is now determined independently of got.

ajhollid

The advanced matcher is ignored in the error path. This is as it should have been before this change, but now that there are codes that could be considered as "up" in the error path, the advanced matcher should be run in those cases.

ajhollid · 2026-06-04T17:28:33Z

+			const statusCode = error.response?.statusCode;
+			const statusUp = isStatusUp(statusCode, monitor.customUpCodes);
+
 			return {
 				monitorId: monitor.id,
 				teamId: monitor.teamId,
 				type: monitor.type,
-				status: false,
-				code: error.response?.statusCode ?? NETWORK_ERROR,
+				status: statusUp,
+				code: statusCode ?? NETWORK_ERROR,


There is an issue here.

If we accept that there are error codes that may actually be considered as "Up", we need to run the advanced matcher here as well.

If a user sets advanced matching and a custom code, their advanced matcher will be ignored.

Fixed this in the latest commit.
It now properly runs the advanced matcher for custom up codes too.
Thank you for the review.

When customUpCodes mark an HTTPError as up, parse the response body, apply advancedMatcher.validate, and set status to statusUp && matchResult.ok. Return parsed payload and extracted values to match the success path.

…us-codes-backend # Conflicts: # server/src/service/infrastructure/network/HttpProvider.ts

ajhollid

There's too much code duplication in the error branch, it's nearly identical to the success branch. Let's extract it to a helper.

ajhollid · 2026-06-05T16:30:47Z

+			const { jsonPath } = monitor;
+			const body = error.response?.body ?? "";
+			const contentType = error.response?.headers?.["content-type"] || "";
+			const isJson = contentType.includes("application/json");
+
+			if (jsonPath && !isJson) {
+				return {
+					monitorId: monitor.id,
+					teamId: monitor.teamId,
+					type: monitor.type,
+					status: false,
+					code: statusCode ?? NETWORK_ERROR,
+					message: "Response is not JSON",
+					responseTime,
+					timings: error.timings,
+					payload: body as unknown as T,
+				};
+			}
+
+			let payload: T;
+			if (isJson) {
+				try {
+					payload = JSON.parse(body) as T;
+				} catch {
+					payload = body as unknown as T;
+				}
+			} else {
+				payload = body as unknown as T;
+			}
+
+			const matchResult = this.advancedMatcher.validate<T>(payload, monitor);
+
 			return {
 				monitorId: monitor.id,
 				teamId: monitor.teamId,
 				type: monitor.type,
-				status: false,
-				code: error.response?.statusCode ?? NETWORK_ERROR,
-				message: error.message,
-				responseTime: error.timings?.phases?.firstByte ?? error.timings?.phases?.total ?? 0,
+				status: statusUp && matchResult.ok,
+				code: statusCode ?? NETWORK_ERROR,


This code is nearly identical to the code in the success branch. This should be extracted to a private helper function

Sure i can create a private method to obey DRY.

feat(backend): add customUpCodes support for HTTP monitors

4e31499

Adds a customUpCodes field to the monitor schema to allow users to specify which HTTP status codes should be treated as UP instead of DOWN. Includes core logic in HttpProvider and unit tests. Refs bluewave-labs#3657

harsh-aghara requested review from Br0wnHammer, ajhollid and karenvicent as code owners May 31, 2026 18:49

ajhollid requested changes May 31, 2026

View reviewed changes

harsh-aghara requested a review from ajhollid June 1, 2026 07:59

Br0wnHammer requested changes Jun 3, 2026

View reviewed changes

ajhollid requested changes Jun 3, 2026

View reviewed changes

refactor(monitor): address PR feedback for customUpCodes

372fc98

Add HttpStatusCode types and simplify provider logic

harsh-aghara requested a review from ajhollid June 3, 2026 18:21

refactor: extract isStatusUp utility to decouple from got's response.…

5628c20

…ok and modified utils test accordingly

ajhollid requested changes Jun 4, 2026

View reviewed changes

harsh-aghara added 2 commits June 5, 2026 00:35

fix: run advanced matcher on HTTP errors with custom up codes

dd16ac0

When customUpCodes mark an HTTPError as up, parse the response body, apply advancedMatcher.validate, and set status to statusUp && matchResult.ok. Return parsed payload and extracted values to match the success path.

Merge remote-tracking branch 'upstream/develop' into feat/accept-stat…

d2c13fa

…us-codes-backend # Conflicts: # server/src/service/infrastructure/network/HttpProvider.ts

harsh-aghara requested a review from ajhollid June 4, 2026 19:38

ajhollid requested changes Jun 5, 2026

View reviewed changes

refactor: introduced helper method to remove redundant code

2b9fa63

harsh-aghara requested a review from ajhollid June 5, 2026 17:17

Uh oh!

Conversation

harsh-aghara commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe your changes

Write your issue number after "Fixes "

Please ensure all items are checked off before requesting a review. "Checked off" means you need to add an "x" character between brackets so they turn into checkmarks.

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

harsh-aghara commented Jun 1, 2026

Uh oh!

Br0wnHammer left a comment

Choose a reason for hiding this comment

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

harsh-aghara commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ajhollid commented Jun 3, 2026

Uh oh!

harsh-aghara commented Jun 4, 2026

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

harsh-aghara commented May 31, 2026 •

edited

Loading

harsh-aghara commented Jun 3, 2026 •

edited

Loading