IFEX / Protobuf-gRPC mapping
Direction Protobuf/gRPC to IFEX:
- Protobuf
message
map to IFEX Struct because it is a kind of structured type definition. Protobuf supports nested messages and these become nested structs, where the nested member also needs an auto-generated name, because in Protobuf it is anonymous. - Protobuf/gRPC
rpc
maps to IFEX Method - Protobuf/gRPC
package
maps to IFEX Namespace - Protobuf/gRPC
service
maps to IFEX Interface - Protobuf
options
can appear on most object types in protobuf and may have slightly different meanings. Options are a kind of catch-all to add information to the objects. This is what IFEX layers are for and layers provide a more powerful and clearer way. Because of its catch-all nature, the meaning of protobuf options might unfortunately be somewhat specific to the user of the protobuf language. When translating interfaces to (or via) IFEX it is required that a general agreement is made when defining a Layer Type that provides the functionality that is/was desired from the use of options. As always, Layer Types are strongly correlated with the implementation of the tools (code-generator / translator / other) that make use of the layer type, and therefore the definition would be clarified in combination with what the desired result is from the tools.
Direction IFEX to Protobuf/gRPC:
- IFEX
Property
have a generic meaning that does not really exist in Protobuf. A Property gets its behavior when translated to a communication protocol or to executing code. A specific IFEX to protobuf/gRPC tool or code-generator may generate get/set methods ('rpcs') on the gRPC protocol level if the code generator and its configuration is set up such that those methods shall be created for the given Property. Similarly, a particular coding environment may provide subscribe/unsubscribe functionality that allows referencing the existing properties. In either case, a protobuf message definition is likely involved to specify the datatype of the data that is being exchanged, unless a primitive type can be used. - IFEX
Event
s similarly have no exact equivalence in protobuf/gRPC but might be generated by a certain translator/code-generator as a Message and/or RPC. Option
s may be used to define additional metadata when protobuf lacks features to properly disambiguate the original IFEX concept, and of course comments can be generated to indicate the original feature meaning.- For other features, refer to the previous mappings, but in reverse.
General
A few idiosyncracies need to be dealt with:
Enumeration
s can appear inside protobuf Messages. In an IFEX translation they are defined at theNamespace
level. Any name-clashes or similar may need to be dealt with by the implementation.- As mentioned above, options serve multiple purposes, and their purpose and definition need to be more specifically identified in a formal IFEX Layer Type.
- Transferring comments are not handled in the first primitive implementation, but can of course be supported in theory
Composite and non-obvious types
Struct
s define types made up of several members. This can be seen as functionally equivalent to protobufMessage
.MapField
corresponds to themap
type in IFEX.- There is no
Set
type in protobuf/gRPC -> translate to a simpler type like an array of type X, and manually ensure the implementation fulfils the Set behavior. As noted above, options might be used to "add metadata" that may affect the implementation behavior.
Errors
Protobuf/gRPC language features, and common definitions (.proto files) that also appear in protobuf and gRPC repositories are not well separated and both might be used by a system that was defined using these specific technologies. There are some conventions to (re)use certain standard definitions.
Similarly, IFEX does not provide standard error types, but the project community may still, optionally, agree on some standard definitions. If definitions such as
google.rpc.Status
are used in an interface definition then a standard translation of that might be created in an IFEX translation of the same. A more recommended approach might be to avoid using the make a definition that is independent of the protobuf/gRPC specific one when moving the interface to the more generic language (IFEX) as this would make things more natural when translating to other IPC/RPC protocols.IFEX also has a richer
errors
concept, where multiple error types can be defined simultaneousy or through overlays, which enables for example separation of business-logic errors from transport errors.