Strongly typed RPC return values?

[phijor]

Over the past few months, many parts of the metricq API gained type annotations that (imo) made the code easier to work with.

One thing that I keep stumbling upon is that for many RPC wrappers, the their return value is either not specified at all, or just described as "whatever JSON we got, converted to a dict".

Prime example, sink.subscribe:

https://github.com/metricq/metricq-python/blob/8e73ceb203a70f5ae8093c218e1eb11f934ea93a/metricq/sink.py#L124-L159

Documentation is simply "returns: rpc response", not really informative. The RPC spec tells us though that it contains useful metric data in response["metrics"].

My question(s):

• Should we have some nice wrapper types for RPC responses, at least where a response reaches API boundaries?
• Should there be proper type aliases that make working with such responses easier? (See e.g. the private alias _GetMetricsResult here)
• Is it desirable to limit what info is leaked at the API boundary? sink.subscribe for example also returns information about data server address and queue. I'd say the only data of value there is the metric metadata. The rest is handled by the implementation.

[tilsche]

I don't have the answers to the questions now, but one thing to consider. The extensibility of the RPCs also applies to the return-"value". An agent should not panic when it receives a response with a key it doesn't know yet. This makes actual type checking more difficult.