Crate magnetar_admin

Expand description

Apache Pulsar admin REST client (/admin/v2/...).

Thin async wrapper around reqwest for the broker’s JAX-RS admin API. TLS is via rustls-tls. There are no channels and no background tasks: every call is a one-shot await that resolves to a Result.

Endpoint paths mirror the broker. Each method’s rustdoc cites the Java endpoint class (file + relevant @Path annotation) in apache/pulsar so a reader can confirm the URL and HTTP verb against upstream.

§Quick start

use magnetar_admin::{AdminClient, TenantInfo};

let admin = AdminClient::builder()
    .service_url("http://localhost:8080".parse()?)
    .build()?;

let tenants = admin.tenants_list().await?;
println!("{tenants:?}");

admin
    .tenant_create(
        "acme",
        TenantInfo {
            admin_roles: vec!["admin".into()],
            allowed_clusters: vec!["standalone".into()],
        },
    )
    .await?;

Structs§

AdminClient: Apache Pulsar admin REST client.
AdminClientBuilder: Builder for AdminClient.
BacklogQuota: Java BacklogQuota — one entry in the namespace-level backlog quota map. policy is a string (producer_request_hold, producer_exception, consumer_backlog_eviction) rather than a closed Rust enum so new broker enum values forward-decode cleanly.
BookieInfo: Java BookieInfo — a single bookie’s rack assignment, as stored in the racks-info metadata path and shipped on AdminClient::bookies_set_rack. Field names are camelCase on the wire (matching org.apache.pulsar.common.policies.data.BookieInfo, which carries only rack and hostname).
DelayedDeliveryPolicies: Java DelayedDeliveryPolicies — namespace-level switch + index-tick granularity for the broker’s delayed-message delivery tracker. Maps to org.apache.pulsar.common.policies.data.DelayedDeliveryPolicies. tick_time controls how often the broker’s delay-index buckets are re-evaluated; smaller values give tighter delivery accuracy at a higher tracker cost.
DispatchRate: Java DispatchRate — a sliding-window throttle (msg/sec + byte/sec over a ratePeriodInSecond window). Shared shape between the per-namespace consumer dispatch rate, the per-subscription dispatch rate, and the cross-cluster replicator dispatch rate.
FunctionConfig: Pulsar Functions configuration — the subset of Java’s org.apache.pulsar.common.functions.FunctionConfig that the URL-based register / update calls actually require. The Java type carries ~30 fields (process / k8s runtime tuning, secrets, deadletter topics, …); we expose the load-bearing ones an operator running a pre-compiled JAR needs. Unknown fields on the wire are tolerated by the broker, so adding extra knobs is an additive change later.
LongRunningProcessStatus: Java LongRunningProcessStatus — the polling shape for triggered background jobs (compaction, offload). The broker returns one of four status values: NOT_RUN (never triggered), RUNNING, SUCCESS, ERROR. last_error is populated only on ERROR.
PackageMetadata: Java PackageMetadata — the metadata envelope Pulsar Packages attaches to each (type, tenant, namespace, name, version) tuple. Mirrors org.apache.pulsar.packages.management.core.common.PackageMetadata (Jackson camelCase on the wire). modification_time is a broker-side timestamp in milliseconds-since-epoch — the broker emits it on GET and ignores caller-supplied values on PUT (overwriting them with the receive timestamp).
PersistencePolicies: Java PersistencePolicies — namespace-level BookKeeper layout + managed-ledger write-shaping knobs. Maps to the broker’s org.apache.pulsar.common.policies.data.PersistencePolicies.
PostSchemaPayload: Java PostSchemaPayload — the request body for AdminClient::schema_post and AdminClient::schema_compatibility_check. The Java DTO has (type, schema, properties); both keys travel as-is on the wire. schema is the canonical-form blob for AVRO / JSON / PROTOBUF and the protobuf descriptor for PROTOBUF_NATIVE.
PublishRate: Java PublishRate — producer-side throttle (msg/sec + byte/sec). -1 on either dimension disables that axis of the throttle. Missing fields default to -1 (not 0) — same sentinel semantics as DispatchRate. Unlike DispatchRate, there is no rate-period field; the broker uses a fixed 1-second window.
RetentionPolicies: Java RetentionPolicies — namespace-level retention policy. -1 for either dimension means infinite. The broker applies whichever quota becomes binding first (time OR size).
SinkConfig: Java SinkConfig — declarative description of a Pulsar IO Sink. Mirrors org.apache.pulsar.common.io.SinkConfig (Jackson camelCase on the wire). The inputs slot is the list of source topics the sink reads from — the broker accepts either fully-qualified topic names or tenant/namespace/topic shorthand. Per-connector knobs ride in configs for the same forward-compat reason as SourceConfig.
SourceConfig: Java SourceConfig — declarative description of a Pulsar IO Source. Mirrors org.apache.pulsar.common.io.SourceConfig (Jackson camelCase on the wire). Only the fields the JAX-RS create / update paths require are typed; per-connector knobs ride along in the open-ended configs map so a forward broker can add fields without a magnetar release.
TenantInfo: Tenant policy info — admin roles and allowed clusters.
TopicStats: Topic stats. Intentionally permissive: the Java PersistentTopicStatsImpl shape is large and shifts between releases; we extract the high-signal counters and pass the rest through as raw JSON.

Enums§

AdminAuth: Authentication strategy used by the admin client.
AdminError: Errors returned by the admin client.
BacklogQuotaType: Java BacklogQuotaType — selects which dimension a BacklogQuota entry limits.
PackageType: Pulsar Packages namespace dimension — the {type} segment of the /admin/v3/packages/{type}/... URL. Maps to upstream’s PackageType enum (pulsar-packages-management/pulsar-packages-management-core/.../ PackageType.java): the broker only accepts the three lowercase tokens function, source, sink and rejects everything else with 400. Modelled as a closed Rust enum so the URL builder cannot emit a value the broker will refuse.

Constants§

DEFAULT_TIMEOUT: Default request timeout. Mirrors PulsarAdminBuilder Java default of 60s (see pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/ PulsarAdminBuilderImpl.java).
PACKAGE_REGISTER_TIMEOUT: Longer per-call timeout for *_create_with_url / *_update_with_url endpoints. The broker fetches the package from the supplied URL before responding, so the round-trip can comfortably exceed 60 s against a slow internal registry (S3 / GCS / function://) or a large .nar / .jar artifact. Overrides the client-level timeout for those calls only — every other admin verb keeps the 60 s budget DEFAULT_TIMEOUT provides.

Functions§

split_function_id: Split a tenant/namespace/name Functions / IO identifier into its three segments. Pulsar Functions never carry a persistent:// scheme prefix (functions are not topics), so the parser is stricter than the internal split_topic (rustdoc cannot resolve the bare identifier because split_topic is module-private).
split_namespace: Split a tenant/namespace string into its two segments.

Crate magnetar_admin

Crate magnetar_admin Copy item path

§Quick start

Structs§

Enums§

Constants§

Functions§

Crate magnetar_admin