Allow interfaces to define common parameters and return types

[bterlson]

One of the bits of magic happening in the rest framework is establishing common parameters and return types for resource interfaces. This has two drawbacks - one, the behavior is accomplished via decorators and so is fairly opaque, and two, custom operations on the interface need to provide the correct (and possibly very complex) parameters themselves.

This problem could be solved in part by going back to one of the very early designs for interfaces which had an interface-level parameter list, but this approach itself has some drawbacks - it doesn't address return types, and it is inflexible in terms of the position of the parameters (i.e., they always came first).

With the addition of templates, we can probably do something better. A basic proposal (names up for bikeshedding) is to add a special operation called opTemplate which takes template parameters for the original arguments and original return type and can be decorated. When Cadl instantiates operations, it runs the opTemplate for any mixed interfaces and the parent interface.

A resource could then look like:

interface MyResource mixes ReadResource<Foo> {
  // add the error response and apply @commonDec to all members
  @commonDec
  opTemplate<TParams, TReturn>(... TParams): TReturn | ErrorResponse;

  // also has the common parameters from the parent interface
  customRead(): Foo;
}

interface ReadResource<T> {
  opTemplate<TParams, TReturn>(... @KeyParameters<T>, ... TParams): TReturn

  @get read(): T;
}

It might be tempting to use this mechanism to wrap everything in the Response envelope, however because cadl unions are never distributive, this won't work without some further modifications:

interface MyResource extends ReadResource<Foo> {
  returnType<TDeclReturn> = Response<TDeclReturn | Error>

  // Now has a return type of Response<Foo | Bar | Error>
  customRead(): Foo | Bar;
}

(TypeScript has the ability for a particular template to opt-in to distributivity via a weird hack but this wouldn't really work for us anyway since I think we need template call sites to specify whether they intend a union to be distributive or not. Though we could have a DistributiveResponse template that uses a callee-side hack ala TypeScript I suppose.)

It might also be interesting to consider similar mechanisms for models and even other declarations, though I don't have any scenarios in mind at the moment.

[johanste]

Would it help if we had a Callable (generic) type?

[daviwil]

It's a good start I think, let me think on it over night and I'll see if I can come up with some alternate syntax suggestions.

[markcowl]

example of operation signatures:

signature ResourceRead<TResource>(...KeysOf<TResource>): TResource | ErrorResponse;

interface SomeInterface {

read: ResourceRead<TResource>;

}

[markcowl]

Notes

• Operation templates seem to the group like a useful addition
• Need to develop this further and apply to common scenario, such as resource actions
• David and Johan to develop the idea of operation templates and come back with a modified proposal

[daviwil]

Discussed this with @johanste, it seems like we may not actually need this feature after all. The two major problems that it could solve are:

1. Reusing and extending common operation parameters
2. Defining default error response types for lifecycle operations and custom actions

For now, our theory is that we can solve #1 by using interface templates, especially if we have named template parameters with default values. This would allow specific parameter sets to be customized in lifecycle operations.

#2 can be solved initially by using Azure-specific resource operation (or interface) decorators which will lint the operations to ensure they at least have the default error response type that is expected for the service.

Let's discuss for a bit in the design meeting tomorrow to decide whether we can close this issue for now and re-open later if more possible use cases present themselves.

[daviwil]

Cadl Operation Signatures

It should be possible to define signature types for operations which can be
reused anywhere a normal operation could be specified:

op ResourceRead<TResource> =
  @autoRoute
  @doc("Get a {name}", TResource)
  @get
  @armResourceRead(TResource)
  (...ResourceInstanceParameters<TResource>): ArmResponse<TResource> | ErrorResponse;

model Widget {
  @key
  id: string;
  name: string;
}

model WidgetProperties {
  weight: number;
}

op getWidget: ResourceRead<Widget>;

Aspects of the design:

• We would use the op keyword in 3 cases:
  • Normal operation declaration
  • Use = to indicate a signature and omit the operation name
  • Use : after operation name and then operation signature type
  • This could be slightly ambiguous!
• Decorators applied to the signature are not executed until it is used to instantiate a real operation
• Decorators applied to the signature definition can possibly modify the signature, but not clear how it'd be useful
• Decorators applied at the site of signature usage will be added to the list of
  decorators that are being brought across by the signature itself (need to de-duplicate?)

Benefits

• Easily cherry-pick operations to use in your interfaces
• Choose what name the operation gets while easily reusing the known signature shape
• Create multiple operations in an interface using the same shape but different
  operation names

Using signatures to improve resource modelling

Here's an example of how we would rewrite out current ResourceOperations<T>
interfaces with operation signatures:

op ResourceRead<TResource> =
  @autoRoute
  @doc("Get a {name}", TResource)
  @get
  @armResourceRead(TResource)
  (...ResourceInstanceParameters<TResource>): ArmResponse<TResource> | ErrorResponse;

op ResourceCreate<TResource> =
  @autoRoute
  @doc("Create a {name}", TResource)
  @extension("x-ms-long-running-operation", true)
  @asyncOperationOptions("azure-async-operation")
  @armResourceCreateOrUpdate(TResource)
  @put
  (...ResourceInstanceParameters<TResource>,

   @doc("Resource create parameters.")
   @body
   resource: TResource
  ): ArmResponse<TResource> | ArmCreatedResponse<TResource> | ErrorResponse;

op ResourceUpdate<TResource, TProperties> =
  @autoRoute
  @doc("Update a {name}", TResource)
  @armResourceUpdate(TResource)
  @patch
  (...ResourceInstanceParameters<TResource>,

   @doc("The resource properties to be updated.")
   @body
   properties: ResourceUpdateModel<TResource, TProperties>
  ): ArmResponse<TResource> | ErrorResponse;

op ResourceDelete<TResource> =
  @autoRoute
  @doc("Delete a {name}", TResource)
  @extension("x-ms-long-running-operation", true)
  @asyncOperationOptions("azure-async-operation")
  @armResourceDelete(TResource)
  @delete
  (...ResourceInstanceParameters<TResource>):
    | ArmDeletedResponse
    | ArmDeleteAcceptedResponse
    | ArmDeletedNoContentResponse
    | ErrorResponse;

op ResourceListBySubscription<TResource> =
  @pageable
  @autoRoute
  @doc("List {name} resources by subscription ID", TResource)
  @list(TResource)
  @segmentOf(TResource)
  @armResourceList(TResource, "ListBySubscription")
  @get
  ListBySubscription(
    ...SubscriptionScope<TResource>
  ): ArmResponse<ResourceListResult<TResource>> | ErrorResponse;
}

op ResourceListByResourceGroup<TResource> =
  @pageable
  @autoRoute
  @doc("List {name} resources by resource group", TResource)
  @list(TResource)
  @segmentOf(TResource)
  @armResourceList(TResource, "ListByResourceGroup")
  @get
  (...ResourceGroupScope<TResource>): ArmResponse<ResourceListResult<TResource>> | ErrorResponse;

op ResourceAction<TResource, TParams, TResponse> =
  @post
  (...KeysOf<TResource>, ...TParams): TResponse | AzureError;

With these operation signatures, we can recreate our original
ResourceOperations interfaces so that spec authors can easily pull in standard
operation sets:

interface ResourceInstanceOperations<TResource, TProperties> {
  Get: ResourceRead<TResource>;
  Update: ResourceUpdate<TResource, TProperties>;
  Delete: ResourceDelete<TResource>;
}

interface ResourceCollectionOperations<TResource> {
  CreateOrUpdate: ResourceCreate<TResource>;
  ListByResourceGroup<TResource>: ResourceListByResourceGroup<TResource>;
  ListBySubscription<TResource>: ResourceListBySubscription<TResource>;
}

interface ResourceOperations<TResource, TProperties>
  mixes ResourceInstanceOperations<TResource, TProperties>,
    ResourceCollectionOperations<TResource> {
}

A spec author can pick and choose which operation shapes to use for their
interfaces, even customizing the operation names with ease:

interface Widgets mixes ResourceInstanceOperations<Widget, WidgetProperties>
  CustomCreate: ResourceCreate<Widget>;
}

[timotheeguerin]

Designed discussed, each operation can be used as a signature. No =.

namespace SharedLib {
  op reusableOp(): string;

  @autoRoute
  @doc("Get a {name}", TResource)
  @get
  @armResourceRead(TResource)
  op ResourceRead<TResource>(...ResourceInstanceParameters<TResource>): ArmResponse<TResource> | ErrorResponse;
}

@serviceTitle("")
namespace MyService {
  op myOp: SharedLib.ResoureceRead<MyResource>;
  op myOp2: SharedLib.reusableOp;
}

// Don't allow
interface Foo {
  ResourceRead<T>(): T;
}