Add Tag Fields to Jobs

[Akopti8]

This PR adds support for optional tags and macID fields when creating job executions, allowing jobs to be labeled and associated with a specific machine/client. These fields are persisted in the job record and returned in job responses, enabling future filtering and better job traceability. The update includes database schema changes for both Postgres and SQLite, updates to job models and API handlers, and documentation updates describing how these fields can be used in the /execution payload. A changelog entry was also added describing these API additions.

Note: I’m not completely sure if I added the changelog entry in the correct format/location according to the project’s conventions, so please let me know if it should be structured differently.

[ar-siddiqui]

@Akopti8, a few things

1. How does tags query parameter work? Can you provide some examples, like if I have tags huc984727 and texas, can I search by just the tag texas. Please provide some details on how this works.
2. I think machine ID should be in a separate PR, also I don't agree with the idea of exposing this detail externally to the users. This should be an internal detail, no?
3. Please add example(s) in the sample Postman collection for tags.
4. Please add tests in the test Postman collection for tags. Test different ways a user can request/submit tags.

[Akopti8]

@Akopti8, a few things

1. How does tags query parameter work? Can you provide some examples, like if I have tags huc984727 and texas, can I search by just the tag texas. Please provide some details on how this works.
2. I think machine ID should be in a separate PR, also I don't agree with the idea of exposing this detail externally to the users. This should be an internal detail, no?
3. Please add example(s) in the sample Postman collection for tags.
4. Please add tests in the test Postman collection for tags. Test different ways a user can request/submit tags.

Thanks, I addressed the tags-related feedback.

For tags, filtering works as an AND match across the provided values. So if a job was submitted with tags ["huc984727", "texas"], then:

• GET /jobs?tags=texas returns that job
• GET /jobs?tags=huc984727 returns that job
• GET /jobs?tags=texas,huc984727 also returns that job

I also added tag examples to the sample Postman collection and added E2E coverage for different tag submission/filtering cases, including with tags provided, omitted, and empty.

On the macID qurstion, I will defer to @slawler on that question.

[Akopti8]

@Akopti8, a few things

1. How does tags query parameter work? Can you provide some examples, like if I have tags huc984727 and texas, can I search by just the tag texas. Please provide some details on how this works.
2. I think machine ID should be in a separate PR, also I don't agree with the idea of exposing this detail externally to the users. This should be an internal detail, no?
3. Please add example(s) in the sample Postman collection for tags.
4. Please add tests in the test Postman collection for tags. Test different ways a user can request/submit tags.

Thanks, I addressed the tags-related feedback.

For tags, filtering works as an AND match across the provided values. So if a job was submitted with tags ["huc984727", "texas"], then:

• GET /jobs?tags=texas returns that job
• GET /jobs?tags=huc984727 returns that job
• GET /jobs?tags=texas,huc984727 also returns that job

I also added tag examples to the sample Postman collection and added E2E coverage for different tag submission/filtering cases, including with tags provided, omitted, and empty.

On the macID qurstion, I will defer to @slawler on that question.

@ar-siddiqui,
Just to add, partial matching also works, for example, a job with tags ["hello", "world"] would be returned by GET /jobs?tags=hel,wor.

Also, Seth had mentioned there might be additional ideas or considerations around how tags should work; would you mind elaborating on what you had in mind there?

Lastly, I’ve removed macID from this branch and can handle it separately if needed.

[ar-siddiqui]

This is great. This partial matching work across the string or only for the prefix? For example, tags=ell would return a job with hello tag or not? Are there tests added to check this functionality?

We should scan user-provided tags to make sure they don't contain URL unsafe characters, for example, , or = in a tag could potentially mess with URL-based querying. Please give this some thought if not already considered.

A future addition could be to allow processes to require some mandatory tags. I think for now we can just add it as an issue for feature enhancement.

[Akopti8]

This is great. This partial matching work across the string or only for the prefix? For example, tags=ell would return a job with hello tag or not? Are there tests added to check this functionality?

We should scan user-provided tags to make sure they don't contain URL unsafe characters, for example, , or = in a tag could potentially mess with URL-based querying. Please give this some thought if not already considered.

A future addition could be to allow processes to require some mandatory tags. I think for now we can just add it as an issue for feature enhancement.

Right now the matching behaves as prefix-based, not full substring. So for example:

tags=tex will match texas

tags=tes would not match

I added tests around tag filtering (single, multiple, and combinations), and I prefix behavior as well.

On the URL safety side, good call! I added validation to reject tags containing unsafe characters like ,, =, &, and ?, and limited allowed characters to a safe set ([A-Za-z0-9._-]) to avoid breaking query parsing.

The idea of required/mandatory tags makes sense, I agree that’s probably best as a follow-up enhancement. I can open an issue for that so we don’t lose track of it.

[ar-siddiqui]

Thanks, let me test it one time and I will then approve.

[ar-siddiqui]

@Akopti8 @slawler My review and updates in #119
I beleive we can merge 117 as soon as 119 is merged.