API stability proposal

[mattklein123]

This is an extension of the conversation started in:
https://docs.google.com/document/d/1eDQQSxqx2khTXfa2vVm4vqkyRwXYkPzZCcbjxJ2_AvA/edit?ts=5af97a4e

Ultimately, we would like to stabilize the API and have a deprecation period like we do for config changes. Getting there is going to take a bunch of thought and a solid plan. We also need to make sure we don't reduce velocity when the project is still relatively young.

Related to #827

cc @brian-pane @htuch @alyssawilk @envoyproxy/maintainers

[htuch]

FWIW, and not that I think it's a good idea, but if we ever want to support binary modules with a stable ABI (e.g. as with vendor supplied Linux kernel binary drivers), this would be needed.

[ggreenway]

I think we should wait for this until the project is more mature. Or at most make this a best-effort idea. I don't want to restrict refactoring and code-cleanup due to out-of-tree code.

[lizan]

I think we should wait for this until the project is more mature. Or at most make this a best-effort idea. I don't want to restrict refactoring and code-cleanup due to out-of-tree code.

That was my feeling when I filed #2925 and I agree. Tough I would love to see some level of API stability for a subset of them.

[dnoe]

Noting here for future reference that PR #6826 was the sort of thing that caused breakage after a subtle internal API change, and we should make sure that the API stability proposal covers this kind of case.

[htuch]

@dnoe are you talking about internal API/ABI stability or Envoy's control and configuration APIs?

[dnoe]

Internal, basically the extensions APIs. We need to think especially carefully about how we communicate and what the process looks like for cases where the API changes in ways that would not immediately break compilation.

[htuch]

Yeah, there's a lot of work to be done here. I actually was confused by the title, it's the same almost as my current proposal on external API stability :)

[mattklein123]

FYI I think the current plan here is to adopt the WASM ABI as our stable filter API.

[htuch]

@mattklein123 any update to thinking here or should we close this out with #3390 (comment) as PoR?

[mattklein123]

@mattklein123 any update to thinking here or should we close this out with #3390 (comment) as PoR?

Sorry which comment as the PoR? I'm not sure we have any good plan here still.

[htuch]

The one I linked to (#3390 (comment)). Basically, we will use Wasm ABI as the only stable ABI for filters (Wasm, C++ NullVm etc).

[mattklein123]

I don't know that we have made any progress on this one way or the other. Practically, the Wasm ABI is the only way today to have any hope of a stable ABI. I would be fine just saying this is the way it always will be but I don't feel super strongly about it.