--
You received this message because you are subscribed to the Google Groups "api-council" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-council...@fuchsia.dev.
I believe we recently changed the guidance on FIDL namespaces to allow three dots (previously, it was two). What was the rationale there? Does this kind of nesting fit with our policy?
= Context =It's a challenge to design a FIDL protocol that (1) allows augmenting an event, (2) have the augmentation scoped to capable clients, (2) avoids mass type and protocol duplication, and (4) retains API and ABI compatibility to existing clients when the event is later extended.
= Proposal =The fuchsia.ui.pointer proposal is an attempt at providing these properties. There are just two protocols in fuchsia.ui.pointer (touch and mouse), and are intended for regular clients. Clients with the right capability (fuchsia.ui.pointer.augment) can "upgrade" their fuchsia.ui.pointer protocol to also carry extra data that they need (examples are accessibility or Sys UI). The server guarantees that extra data is never sent to regular clients. Furthermore, when a new augmentation need comes along, we can add the capability and its data without impacting both regular clients and existing augmented clients.
These nice properties need some help to express in FIDL. The FIDL compiler enforces a DAG structure on libraries. To accommodate that constraint, regular clients write code against:(P) fuchsia.ui.pointer ("fup"), defining protocols and just its top-level data types, and(D) fuchsia.ui.pointer.data ("fup.data"), defining the remaining data types,and augmented clients write code against(A) fuchsia.ui.pointer.augment ("fup.augment"), defining the augmentation protocols,(E) fuchsia.ui.pointer.augment.data ("fup.augment.data"), defining the extra data, which may reuse types in fuchsia.ui.pointer.data.These FIDL libraries result in a striated dependency structure:(topmost) A -(depends on)-> P -(depends on)-> E -(depends on)-> D
= Questions =Reviewers may notice the tension between nested library names (fup.data, fup.augment, fup.augment.data) and the nesting guidance given in the FIDL Rubric:
On the other hand, these library names follow a natural structure between protocol and data, and follows the "no mutli-word" guidance of the same Rubric:as well as the "functional roles with meaning" guidance of the Style Guide:Q1. Is this proposal an appropriate use of nesting for fup.data, fup.augment, and fup.augment.data?
Q2. Can we promote "fuchsia.ui" to generally allow 3 dots in its namespaces?
The "upgrade" pattern, where clients that receive fup.augment.MoreStuffProtocol can have their fup.RegularProtocol decorated with fup.augment.data.MoreStuff, seems new.
Q3. What do you think about this upgrade pattern?
= Context =
It's a challenge to design a FIDL protocol that (1) allows augmenting an event, (2) have the augmentation scoped to capable clients, (2) avoids mass type and protocol duplication, and (4) retains API and ABI compatibility to existing clients when the event is later extended.
--
Returning to the original problem statement:= Context =
It's a challenge to design a FIDL protocol that (1) allows augmenting an event, (2) have the augmentation scoped to capable clients, (2) avoids mass type and protocol duplication, and (4) retains API and ABI compatibility to existing clients when the event is later extended.Is this conflating the FIDL specification, which defines the syntax of protocol messages, with the semantics of the protocol that uses it?For a protocol to introduce additional fields to events, or to replace one field with another, the most flexible tends to be feature opt-in. Augments to events are defined in the FIDL protocol, but will only actually be sent to clients that explicitly opted-in to them, e.g. via an "init" message when first connecting.
The other common approach is to "version" the protocol, which can take the form of switch to an entirely separate syntax, but more commonly also just defines which messages may be exchanged.
Is there a specific need motivating defining separate protocols for these extra fields?
On Fri, 12 Feb 2021 at 05:35, 'Pascal' via api-council <api-c...@fuchsia.dev> wrote:= Context =It's a challenge to design a FIDL protocol that (1) allows augmenting an event, (2) have the augmentation scoped to capable clients, (2) avoids mass type and protocol duplication, and (4) retains API and ABI compatibility to existing clients when the event is later extended.That's true. It is a key deliverable of the FIDL team to design an evolution story for protocols, my hope is that we have something in good shape by mid-year (design wise) with an implementation completed by early 2022.= Proposal =The fuchsia.ui.pointer proposal is an attempt at providing these properties. There are just two protocols in fuchsia.ui.pointer (touch and mouse), and are intended for regular clients. Clients with the right capability (fuchsia.ui.pointer.augment) can "upgrade" their fuchsia.ui.pointer protocol to also carry extra data that they need (examples are accessibility or Sys UI). The server guarantees that extra data is never sent to regular clients. Furthermore, when a new augmentation need comes along, we can add the capability and its data without impacting both regular clients and existing augmented clients.To make sure I understand the strategy, let me try to paraphrase what I'm seeing:
- Some data is shared repeatedly by a server, and represented as some table T (e.g. a TouchEvent)
- This table T has many fields, but only a base set of fields are filled by the server. For instance, while the table may have 20 fields, only 4 are set by default.
- A client can request to upgrade, indicating to the server that it is capable (and interested) in receiving more fields.
- If the server agrees to the upgrade, subsequent data shared by the server will fill in more of the fields of the table T (say maybe 12 out of the 20 for instance, 8 more than previously).
Is this correct?
These nice properties need some help to express in FIDL. The FIDL compiler enforces a DAG structure on libraries. To accommodate that constraint, regular clients write code against:(P) fuchsia.ui.pointer ("fup"), defining protocols and just its top-level data types, and(D) fuchsia.ui.pointer.data ("fup.data"), defining the remaining data types,and augmented clients write code against(A) fuchsia.ui.pointer.augment ("fup.augment"), defining the augmentation protocols,(E) fuchsia.ui.pointer.augment.data ("fup.augment.data"), defining the extra data, which may reuse types in fuchsia.ui.pointer.data.These FIDL libraries result in a striated dependency structure:(topmost) A -(depends on)-> P -(depends on)-> E -(depends on)-> DWhy is there a need for more namespaces than `fuchsia.ui.pointer`? I would expect to have everything in the same namespace.
= Questions =Reviewers may notice the tension between nested library names (fup.data, fup.augment, fup.augment.data) and the nesting guidance given in the FIDL Rubric:On the other hand, these library names follow a natural structure between protocol and data, and follows the "no mutli-word" guidance of the same Rubric:as well as the "functional roles with meaning" guidance of the Style Guide:Q1. Is this proposal an appropriate use of nesting for fup.data, fup.augment, and fup.augment.data?I would start with the general advice about Library structure, specifically "To decide whether to decompose a library into smaller libraries, consider the following questions:"> Do the customers for the library break down into separate roles that would want to use a subset of the functionality or declarations in the library?From what you describe above, the breakdown of clients is stages in time (evolution requirements), or different stages of complexity (simple clients vs advanced clients). So there might be a useful breakdown along the complexity axis, but unlikely along the evolution axis since overtime all should gravitate towards the "new".
> Does the library correspond to an industry concept that has a generally understood structure?Is there an industry precedent for categorising pointer event data that could guide the design here?
> Do many other libraries depend upon the library?This one question feels the weakest in terms of providing guidance, especially since we hope to provide visibility rules to mitigate this problem.Q2. Can we promote "fuchsia.ui" to generally allow 3 dots in its namespaces?I'm not convinced yet that this reason exists :)The "upgrade" pattern, where clients that receive fup.augment.MoreStuffProtocol can have their fup.RegularProtocol decorated with fup.augment.data.MoreStuff, seems new.(I'm going to assume my summary above is correct... but if I'm off, then the next section is going to be off too!)This is one example of protocol negotiation, one technique for protocol evolution. Another example -- on a per request basis, and not per connection basis -- is the fuchsia.io2/Node.GetAttributes method and its NodeAttributesQuery bitset.
Regarding the namespace aspects: can we just put all of the *.data bits into fuchsia.ui.pointer? That feels most intuitive to me but maybe there is a reason. That way in code you get fuchsia.ui.pointer.TouchData, fuchsia.ui.pointer.MouseData, etc. In terms of privilege it's the ability to upgrade a channel that we'd like to guard and not the fact that some clients are capable of receiving extra fields.
Regarding the namespace aspects: can we just put all of the *.data bits into fuchsia.ui.pointer? That feels most intuitive to me but maybe there is a reason. That way in code you get fuchsia.ui.pointer.TouchData, fuchsia.ui.pointer.MouseData, etc. In terms of privilege it's the ability to upgrade a channel that we'd like to guard and not the fact that some clients are capable of receiving extra fields.Yes, but also we get fuchsia.ui.pointer.LocalHitData, fuchsia.ui.pointer.GlobalViewMouseThingy, etc in that namespace. We could certainly merge it all! It feels like a question of priorities and values.Does the desire to "avoid nesting too deeply" [1] trump the desire to "help FIDL developers navigate the API surface" [2] and "provide structure to ... scope FIDL decls within FIDL libraries" [3]?When would we say the latter (structuring on roles) is more important than the former (avoid deep namespacing)? How does API Council proceed here?
--