Improve client middleware documentation

[koevskinikola]

Description

There is very little information on how Camunda users can set up custom client middleware. The only mention is here.

One reason for this lack of documentation is that client middleware is implementation dependant, i.e. depending on the (Zeebe) client implementation (ex. NodeJS, Java, Spring, Go, CLI, etc.), the middleware API will vary depending on the (REST) HTTP client that is used, as well as the gRPC client implementation.

Client middleware is currently supported for:

• Zeebe java client / Spring SDK
  • For REST through the Apache HttpClient 5 AsyncExecChainHandler interface.
  • For gRPC through the grpc-java ClientInterceptor interface.

Tasks

Preview Give feedback

1. Add example implementations of common use-cases for custom middleware for the Camunda Java client #4377
   kind/enhancement target:8.6 +2
   
2. Define the "client middleware" term in the glossary

[koevskinikola]

@akeller I need a bit of help with providing some additional documentation for client middleware. The ZPA team noticed that we don't have a lot of (any) documentation on custom client middleware.

Client middleware is a bit tricky because support for it depends on the client implementation (so it can be unsupported as well). So I'm not sure what would be the best way to provide and structure the documentation for this feature.

As a first step, I think it would be good to add some additional examples for the Java client here.

We currently have the following clients with middleware support:

• Zeebe java client / Spring SDK
  • REST API - supports middleware
  • gRPC - supports middleware
• Go / CLI client - deprecated
  • gRPC - not clear, needs to be clarified
  • REST API - not supported
• NodeJS SDK
  • gRPC - not clear, needs to be clarified
  • REST API - not clear, needs to be clarified

For server (Gateway) middleware we have the following pages:

• Interceptors (gRPC)
• Filters (REST API)

[akeller]

@koevskinikola I am deep in notifications after my FTO. Is there a deadline or timeline for this? I don't want to block you, but I don't know the urgency.

[jwulf]

I have questions.

Are customers asking for this? Do we have any support requests or forum posts about using client middleware?

The example given in the docs is to create a metrics counter for jobs. I can see how customers could use this for dynamic worker scaling.

But is anyone doing this?

I ask this for two reasons:

1. Framing this in documentation needs to have not only "how to I do this", but "why would I do this". Or in other words: "what is this feature?"

2. Related to this - if I implement this for the JS SDK: what am I implementing? The design of the feature needs to match the intended use-cases. And would I be implementing something that customers actually want and will use? How I design and document such a feature would lean heavily on the use-case.

I think we need to get a clearer picture of the user's world. Do we have any examples of customers using client middleware?

[koevskinikola]

Hey @akeller, it would be good if an example is added for the 8.6.0 release.

Other tasks are not as urgent, we can address any bigger restructuring or expansion on these docs with later versions.

@jwulf yes, we had a support case (internal link) from a customer that asked for help with some middleware setup. @megglos and @tmetzke also agree that this would be a good UX improvement. (internal Slack thread)

I think we need to get a clearer picture of the user's world. Do we have any examples of customers using client middleware?

My guess is that one of the reasons why our docs are lacking in the client middleware area is because it's difficult to get more information on how our users use middleware. We can have a look on how we handled the docs on C7 plugins as their usage is similarly very general and a lot of implementations are not public (or shared).

[jwulf]

Ah, OK. In that case - middleware would be a way to address this issue: camunda/camunda-8-js-sdk#246

[akeller]

Client middleware is a bit tricky because support for it depends on the client implementation (so it can be unsupported as well). So I'm not sure what would be the best way to provide and structure the documentation for this feature.

Great opportunity to be opinionated and even somewhat flexible by adding it as a Best Practice > Development. This would allow us to add a bit more narrative to why we are recommending certain way and (hopefully) provide some programming language agnostic way for users not in the Java ecosystem to understand what's going on and possibly build something similar themselves. If we don't have time for that now, that's ok. It's also ok to tell me that doesn't make sense here.

As a first step, I think it would be good to add some additional examples for the Java client here.

Adding it as an example also makes a lot of sense, following the existing pattern (description, prerequisites, code snippet) like this. Would this be a good quick win?

We don't use the term "client middleware" very often in our docs, so let's define it in our glossary too.

@koevskinikola ping me tomorrow if you need more guidance to get something started here.

[korthout]

@akeller the target/* should only be used to highlight items that must make it into that specific release. AFAIK, there is no specific reason why this must be in the 8.6 release, apart from that it would be nice to have. If that assumption is correct, please remove the target:8.6 label.

[koevskinikola]

@akeller I created a separate issue for the additional Java client example, and labeled it with target:8.6. We can remove any mentions of a Camunda version in this issue until we know when we can deliver it.

Unfortunately, with the prior 1 topics, I'm not sure when it will happen.

UPDATE:

Adding it as an example also makes a lot of sense, following the existing pattern (description, prerequisites, code snippet) like this. Would this be a good quick win?

Sorry @akeller, I forgot to reply to your message. Yes, I'll add the example in the format you linked. It's a good quick win.