Add --state filter flag to pulsar-admin functions list

[david-streamlio]

Search before reporting

• I searched in the issues and found nothing similar.

Motivation

IMHO, it's kind of annoying that pulsar-admin functions list doesn't distinguish between running functions and stopped ones. If you have a namespace with a mix of active and stopped functions, there's no way to quickly see which ones are actually running without checking each one individually.
This bash one-liner solves that, but it shouldn't be necessary:

for function in $(pulsar-admin functions list --namespace $NAMESPACE --tenant $TENANT); do
  echo $function
  pulsar-admin functions status --namespace $NAMESPACE --tenant $TENANT --name $function | fgrep running
done

This is slow and noisy — it makes N+1 API calls just to answer "what's currently running?" It would be much more useful if functions list supported filtering by runtime state directly.

Solution

Add optional filter flags to pulsar-admin functions list:

--state flag
Filter functions by their running state.

# Show only running functions
pulsar-admin functions list --tenant public --namespace default --state RUNNING

# Show only stopped functions
pulsar-admin functions list --tenant public --namespace default --state STOPPED

Accepted values: RUNNING, STOPPED (and potentially FAILED, UNKNOWN to cover all states returned by functions status).

--long / -l flag (optional, nice-to-have)
Show extended output with status inline, similar to ls -l:

NAME                        STATE      INSTANCES
add-offset-function         RUNNING    1/1
topic-filter-key            STOPPED    0/1
my-dedup-function           RUNNING    3/3

Alternatives

Benefit

Eliminates the N+1 API call pattern shown above
Makes it practical to monitor function health from scripts and CI/CD pipelines
Consistent with other pulsar-admin subcommands that support filtering (e.g., topics list)
Reduces operational friction for namespaces with many functions

Compatibility

This is a purely additive change. Without any flags, functions list behaves exactly as it does today.

Anything else?

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[onceMisery]

Could you assign it to me?

[onceMisery]

@david-streamlio Hello！I have some implementation details that I need your help to confirm.

Server-side Filtering

Add a state query parameter to the Worker REST endpoint. The server performs filtering and returns the result. This involves a single API call and delivers optimal performance, but requires changes to the API interface, Worker implementation, and REST endpoint.

Client-side Filtering

The CLI layer first retrieves the function list, then queries the status one by one for filtering. No server-side changes are needed, but it results in N+1 API calls, which is slow under large namespaces.

Hybrid Approach

Add a new server-side API for batch status retrieval (e.g., listFunctionsWithStatus). The CLI fetches all functions and their statuses in one call, then performs filtering and formatting on the client side.