More flexible typing for service objects

[jclark]

For Listeners such as HTTP and GraphQL, the type of the resource and remote methods is used to express how the application constrains the use of the protocol. The Listener uses the type of the resource and remote methods to validate whether incoming requests satisfy these constraints and to map from protocol-defined datatypes onto application-defined datatypes.

The service object type needs to be able to describe the possible types that the Listener supports. For example, a Listener might support any type that is a subtype of anydata. Because of contravariance of parameter types, it would not be correct for the service object type to specify the parameter type as anydata. We need additional typing flexibility to be able to describe this.

[jclark]

This builds on #559 and goes together with #608.

[hasithaa]

Update: Currently, developers use compiler plugins to perform this validation. The practice involves defining distinct service object types (usually empty or containing the required remote functions). Compiler plugins then validate the service declarations based on these types. Specifically, service declarations with listener attachments are validated by deriving the service type from the listener's attached method.

Recently, we discussed whether we could enhance service type support to better meet current requirements.

• Optional Remote Methods: Allow flexibility in defining optional remote methods. (related to Allow service types to have methods that do not have to be implemented #1320)
• Validation of Resource Accessors: Ensure only allowed resource accessors are used.
• Validation of Resource Paths: Verify that resource paths follow the correct structure.
• Network-Aware Parameters: Introduce optional parameters like Context, Client, or Caller and validate their presence and return types.
• Data Binding Enhancements: Support data binding for resources/remote methods and expand to include headers, payloads, attachments, etc.

While working on these improvements, we identified areas where type-checking is currently loosely enforced. For example:

• Parameter Overloading: Certain methods allow overloading, leading to inconsistencies.
• Parameter Order: A lack of unified parameter ordering complicates enforcement.

The primary use case for these enhancements is to streamline compiler plugin validation and enable the library itself to provide the necessary details. This would better support developer tools such as Language Servers (LS) and low-code views.
After reviewing the requirements, we discussed that the best approach would be to use annotations to describe this information on the service type. These annotations would enable the creation of a data model (similar to a JSON Schema) based on the annotation values. This model can then be used by compiler tools to perform validation efficiently.