Changes to service framework

[aricart]

Overview

Changes to the service API to simplify its usage and future enhancements.

Remove schema from Service API

See changes to service/micro framework document PR 219

Change INFO response to contain endpoint details

See Change INFO response to contain endpoint details document PR 221

Clients and Tools

• [x] Schemas @ripienaar 1. https://github.com/nats-io/jsm.go/pull/448 2. https://github.com/nats-io/jsm.go/pull/452
• [x] CLI @ripienaar https://github.com/nats-io/natscli/pull/804
• [x] Go @piotrpio 1. https://github.com/nats-io/nats.go/pull/1270 2. https://github.com/nats-io/nats.go/pull/1277
• [x] Java @scottf 1. https://github.com/nats-io/nats.java/pull/916 2. https://github.com/nats-io/nats.java/pull/918
• [x] JavaScript @aricart 1. https://github.com/nats-io/nats.deno/pull/514
• [x] .Net @scottf 1. https://github.com/nats-io/nats.net/pull/774 2. https://github.com/nats-io/nats.net/pull/785
• [x] C @levb 1. https://github.com/nats-io/nats.c/pull/663
• [ ] Python @wallyqs
• [ ] Ruby @wallyqs
• [x] Rust @Jarema @caspervonb 1. https://github.com/nats-io/nats.rs/pull/972

Other Tasks

• [ ] docs.nats.io updated @bruth
• [ ] Update ADR to Implemented
• [ ] Update client features spreadsheet

Client authors please update with your progress. If you open issues in your own repositories as a result of this request, please link them to this one by pasting the issue URL in a comment or main issue description.

[oderwat]

May I ask why this got removed? We found it excellent and used it already. Now we need to resort to the endpoint metadata, and as of now, these can only be queried through the "STATS". It seems that this metadata also is not really considered to be "there"? See: https://github.com/nats-io/nats.go/pull/1270#issuecomment-1564088636

We think that having the schema and documentation information with the endpoints has many advantages, and seeing it in micro inspired us to use this instead of our own ideas about services that document themselves.

[ripienaar]

@oderwat it would really help if you restricted your comments to one place. You are talking about this in 3 places now and it’s confusing

We like the idea of schemas to be clear but we felt until we have a clear strategy around it and perhaps some higher order integrations that’s more opinionated we would rather remove something now that’s perhaps a bit open ended and half baked and later return with better schema support. Rather than be stuck with a inadequate design for the long term one micro is GA

[oderwat]

Sorry for jumping around. I did not understand the connections between the issues at first.

Well, we have our concept for the schemas which is our [avrox](https://github.com/metatexx/avrox, that allows minimal message sizes, optional compression, versioning and full documentation through itself and a central registry, and we wrote tooling around that to automatically discover the schemas, auto-generate it from go structs, debug it through the "nats cli --translate" and some more features like supporting union responses because of the possibility to discover the actual schema used from the first bytes of the message, when given a list of possible ones. As this is not JSON but has a JSON schema description, this matched what was already implemented.

Here is an example output of a prototype tool that lists the schema usage:

tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.version="0.1.1+738.20230525235432.main-96c21daae5f6-dirty"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.meta.hostname="ibuero"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.meta.server="river"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.meta.type="microx"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.subject="tspwa.v1.account.create"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.avrox_res.CreateMsgReplyV1.nsv="10.1.1"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.avrox_res.CreateMsgReplyV1.doc="CreateMsgReplyV1 is the answer on the create endpoint"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.avrox_res.LiveMsgErrorReplyV1.nsv="10.4.1"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.avrox_res.LiveMsgErrorReplyV1.doc=""
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.avrox_req.BasicString.nsv="1.1.1"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-manager.avrox_req.BasicString.doc="BasicString is the container type to store a string in a single avro schema"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-health.subject="tspwa.v1.account.health"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-health.avrox_res.BasicMapStringAny.nsv="1.4.1"
tspwa-service.nvQtxSnGk7Q5r0wtQ3fd9w.endpoint.account-health.avrox_res.BasicMapStringAny.doc=""
tspwa-server.DuPwSEBZhABaFGn0bzXU02.version="0.4.12+595.20230525234655.main-96c21daae5f6-dirty"
tspwa-server.DuPwSEBZhABaFGn0bzXU02.meta.hostname="ibuero"
tspwa-server.DuPwSEBZhABaFGn0bzXU02.meta.server="river"
tspwa-server.DuPwSEBZhABaFGn0bzXU02.meta.type="microx"
tspwa-server.DuPwSEBZhABaFGn0bzXU02.avrox_msg.StatsEntryV1.nsv="10.5.1"
tspwa-server.DuPwSEBZhABaFGn0bzXU02.avrox_msg.StatsEntryV1.doc=""
tspwa-server.DuPwSEBZhABaFGn0bzXU02.avrox_msg.StatsEntryV1.subjects="tspwa.v1.accounts.*.store.stats.>"

We can do the same with just the micro top-level metadata, though. But I liked it much better to add this at the endpoint level.

I am still not clear if the endpoint metadata is supposed to exist or not. If not, please remove this from the code too, so we are forced to rewrite our code to match the "specs".

[Jarema]

#221 has been added to this issue.

I'm not creating a new issue to avoid noise.

Unticking progress of all clients. When your client is compatible with both PR's, please tick your client again.