rfc19: specify json encoding rules for FLUIDs

[garlick]

Problem: it is not safe to encode FLUIDs as JSON numbers, yet we currently do that routinely in Flux.

Require a string encoding going forward.

Note: the proposed language allows any valid FLUID string encoding since they are unambiguous and the public API functions flux_jobid_encode(3) and flux_jobid_parse(3) are available. However, @dirkschubert-linaro requested that a single encoding be used for human readability. Thoughts on whether that should be required? It doesn't cost anything to narrow the requirement to one encoding AFAICS such as f58plain

References

• some JSON implementations may not be able to handle the full range of job IDs encoded as JSON numbers flux-core#6171

[github-actions]

⚠️ linkcheck failed with status code 2

[grondo]

Using F58 is a good idea IMO since this saves space in the encoding and is what users are used to seeing in tools.

Note that requiring an encoding here is the easy part, but doesn't solve the issue of updating or transitioning every use in existing RPCs, eventlogs, and APIs (IOW, the code will immediately be violating this RFC and there's no plan to bring it into compliance). Hopefully specifying the requirement here doesn't limit the design space of a transition plan.

It is too bad we can't exend the JSON pack/unpack syntax to allow new format types...

[garlick]

OK, f58 then. Will fix.

Note that requiring an encoding here is the easy part, but doesn't solve the issue of updating or transitioning every use in existing RPCs, eventlogs, and APIs (IOW, the code will immediately be violating this RFC and there's no plan to bring it into compliance). Hopefully specifying the requirement here doesn't limit the design space of a transition plan.

I think the point of putting it in the spec is to raise the urgency and hopefully curtail the practice in new development. If we just said "SHALL NOT use JSON numbers" then we might end up with multiple new representations so IMHO we ought to just pick one now. Either f58 or f58plain encoding is fine with me.

BTW your idea of adding new fields to existing payloads and phasing out the non-compliant ones sounds right to me.

[garlick]

Were you thinking we should add something about transitioning to the RFC like

Legacy code that uses JSON numbers to represent FLUIDs SHOULD transition to F58 strings by 1) adding a new key name for the string value that that is preferred over the old one when present 2) after a transition period, removing the old key name

[github-actions]

⚠️ linkcheck failed with status code 2

[dirkschubert-linaro]

However, @dirkschubert-linaro requested that a single encoding be used for human readability.
OK, f58 then. Will fix.

This was not my intention when starting flux-framework/flux-core#7378. While I might prefer F58, I am happy with any string encoding.

Require a string encoding going forward.

[grondo]

That makes sense. I was just slightly uncomfortable with specifying an encoding in the RFC without determining the transition plan. However, that was just fear of the unknown and your point is compelling.

[garlick]

How about this then?

• SHALL NOT use JSON numbers
• RECOMMENDED to use JSON strings with f58 encoding
• RECOMMENDED to use the name idstr for the key