Decide how v4 model should handle binding extension breaking changes

[ejizba]

For example the Cosmos DB extension is changing "collectionName" to "containerName" and "connectionStringSetting" to "connection", which affect our Cosmos DB types: https://github.com/Azure/azure-functions-nodejs-library/blob/v4.x/types/cosmosDB.d.ts

Obviously we don't want to do a breaking change release of our library every time a binding extension changes something, so we should make a plan for how we want to handle this, ideally before we GA v4. This was brought up in a programming model sync today as the Python folks are also deciding on a plan.

[jacobpoldenzuhlke]

Doesn't this have a bigger impact than just naming? From what I understand this change includes support of managed identity connections. Not including these naming updates prevents users of the npm package to use the managed identity features?

[ejizba]

The problem is really only with the TypeScript types. Under the covers we just pass along whatever values were given to us, meaning this is not blocking JavaScript users and TypeScript users just need to mess with the types (cast it to any or something) to get the build to pass and they're also fine.

Another workaround is to use generic inputs/outputs: https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-node#generic-inputs-and-outputs

Let me know if you can or can't get it working. We still want to figure this out before GA, but for now I think there's plenty of workarounds.

[jacobpoldenzuhlke]

We ended up using v3 current GA for the cosmos trigger - we have a couple of function apps which meant the impact was isolated and low. I would still like to see a worked example of how the v4 model can be used to allow for cosmos db triggers using managed identity in TS.

Appreciate there might be a bit of a hack with TS types but from my PoV when it starts to become hacky it's hard to justify the approach when v3 is perfectly usable even if it means we have to return back to a function.json setup.

[ejizba]

Had a discussion during today's sync and wanted to document some people's thoughts. First of all, the docs say v2 and v4, but the extension version is v3 and v4 so sounds like we should use v3 and v4.

Next, here are the options I remember being proposed (with greatly simplified examples):

Option 1

Make the Cosmos team own this discussion and make them decide what to do here

Option 2

Provide both versioned types separately, and explicitly choose a default.

export type CosmosDBTriggerOptions = CosmosDBv4TriggerOptions;

export interface CosmosDBv3TriggerOptions {
    connectionStringSetting: string;

    collectionName: string;
}

export interface CosmosDBv4TriggerOptions {
    connection: string;

    containerName: string;
}

Option 3

Provide both versioned types separately, and make the default an "or" of both types so that both work by default (but it helps prevent mixing).

export type CosmosDBTriggerOptions = CosmosDBv3TriggerOptions | CosmosDBv4TriggerOptions;

export interface CosmosDBv3TriggerOptions {
    connectionStringSetting: string;

    collectionName: string;
}

export interface CosmosDBv4TriggerOptions {
    connection: string;

    containerName: string;
}

Option 4

Provide one combined type with all names on one type

export interface CosmosDBTriggerOptions {
    connectionStringSetting: string;

    collectionName: string;

    connection: string;

    containerName: string;
}

Option 5

Split out a separate npm module, something like @azure/functions-cosmosdb where you could have multiple major versions supporting different versions of bundles. We were already thinking of splitting out a new package when we have "rich binding support" involving the cosmos db sdk types.

[lilyjma]

Not sure if we have enough time if we want to go with Option 1 (seems to need more coordination with Cosmos team) or 5 (when will we actually support rich SDK types for cosmosDB?).

Option 2 - we discussed how it works with Bundles v4 only, and we'll need to let existing users that aren't using v4 (majority of them) know they need to move to Bundles v4 if they want to use v4 model.

Option 3 - this will expose to users something that they probably weren't aware of/didn't have to care about previously, i.e. there are different extension versions. We'll suggest that they use the v4 extension since v3 will retire soon. A natural question users might ask would be why have v3 as an option then (it's because of the bundles problem above, which many aren't aware of).

Option 4 - we'll have two property names associated with a retired version of an extension later when we retire v3.

Thinking about this again. I'm leaning towards Option 2. (I know I didn't in the meeting.) My reason is the following:

• we want fewer people to use CosmosDB extension v3 (since it'll retire soon)
  • also don't want users of the new model to be using something that will retire soon
• if existing users are already rewriting their code to use the v4 model, making a change to the bundle version in host.json is an easy step (we can add that in our migration guide)
• we'll bring people's attention to bundles (which few know about) and give a reason to use the v4 bundles

[ejizba]

Discussed with Lily/Hossam in sync today and we'll go with option 3 as it's the easiest option that works regardless of which cosmos extension people use.

We will update the templates to use the v4 extension, so that should address some of the concerns Lily mentioned. Also, we're not stuck with the v3 types forever - we can remove them in the next major version of our package.