ably
Document extras.headers attributes
Whilst we added extras to messages, customers at present are not permitted to use any of these attributes (apart from push) as all attributes are reserved by Ably for future use.
We should reserve a single attribute such as metadata or headers for customers to use.
I think we generally agreed headers was best.
Note that in time, these custom headers may become more useful when we implement streaming query language functionality.
@paddybyers @SimonWoolf are you happy with me to create a PR to update the spec and documentation to reflect this?
┆Issue is synchronized with this Jira Task by Unito
@paddybyers assigning to you to assign on please as I can't do this now, but I think would make sense to do so that we reducing the likelihood of introducing breaking changes down the line.
Do we convert this into a JIRA ticket then?
To more closely follow other message patterns (i.e. HTTP), would headers be something that can appear at the top level, or are there established reasons it needs to be embedded within extras ?
Extras is a root level attribute of the Message object. We added extras so that we had a flexible set of metadata attributes for a Message object, that could be used for anything we want. See Message in https://docs.ably.io/client-lib-development-guide/features/#idl.
If we added another attribute, we'd need to change every SDK and the protocol, and I don't see what the benefit of that would be. Why do you want this?
headers is now permitted, and all other fields are now rejected by realtime.
As such, rolling out documentation now to reflect this ASAP is important.
cc @MarkWoulfeAbly
when documenting this, pls note that headers must be a flat object, map<string, string> or equivalent - no further nesting.
(also we recommend that if using unenveloped reactor rules, header names should be ascii, as the headers will ultimately be turned into http/amqp/etc. headers)
➤ Tony Bedford commented:
I’ve put it at the top of the DOCS backlog for attention in the next sprint.
➤ Tony Bedford commented:
Not sure why sync bot closed. I have put back on the backlog until I can take a look.
➤ Automation for Jira commented:
The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-2799
![sync-by-unito[bot] avatar](https://avatars.githubusercontent.com/in/64202?v=4 "Published by a pub.dev verified publisher"){kind=small}
@QuintinWillison this is an issue to document it, so probably docs rather than spec repo?
(the spec already says extras is an untyped object that sdks should treat opaquely, TM2i)
Good spot, @SimonWoolf. Thanks. I'll transfer this back to the docs repository...
