Skip to main content

Auth and transport

Transport model​

The public gRPC API uses standard gRPC transport semantics over HTTP/2.

First-party clients in this repo apply a shared endpoint tuning helper before dialing. That helper enables:

  • TCP_NODELAY
  • TCP keepalive
  • HTTP/2 adaptive flow control
  • explicit connection and stream window sizing
  • heartbeat and idle timeout tuning unless keepalives are disabled

That is a good default baseline for custom clients as well, especially for long-lived streams and large file transfers.

Outbound authentication and client metadata​

The shared gRPC utilities build outbound metadata with these headers:

  • authorization: Bearer <token>
  • x-aetherfs-client-name: <client-name>
  • x-aetherfs-client-version: <client-version>

The authorization metadata is the primary auth mechanism documented by the public client helpers.

The client identity headers are optional, but they are worth sending from production integrations so server-side logs and support tooling can distinguish your caller.

Scope families recognized by the public surface​

The shared auth layer recognizes these canonical scope families on the public surface:

  • tenant.session.read
  • tenant.session.write
  • tenant.session.delete
  • tenant.session.merge
  • tenant.source.read
  • tenant.source.write
  • tenant.source.delete
  • tenant.source.import
  • tenant.filesystem.read
  • tenant.filesystem.write
  • tenant.filesystem.metadata
  • tenant.usage.read
  • tenant.admin
  • cluster.admin

The server still recognizes legacy aliases for some scopes, but new integrations should use the canonical tenant.* names above.

Reflection support​

The server enables gRPC reflection. That matters for:

  • grpcurl list
  • grpcurl describe
  • schema inspection during support and debugging

Reflection is intended to expose the supported public gRPC surface rather than internal service contracts.

If reflection is disabled in a specific environment, you can still call the API with local proto files, but the out-of-the-box operator experience is designed to work with reflection-aware tools.

Compression​

FileSystemService is configured to accept and send gzip compression on the server side. That is especially relevant for:

  • large streamed reads
  • streamed writes
  • tarball export and import

Do not assume every public service has the same compression profile. If you are building a generic client, treat compression as a per-service capability rather than a blanket API-wide rule.

Binary payloads​

Several public gRPC RPCs use bytes fields or full streaming bodies. Examples include:

  • file reads and writes
  • tarball import and export
  • source archive upload
  • health report payloads
  • message-bus payloads

For those flows, generated clients are usually a better fit than hand-crafted tooling.

grpcurl is still useful for inspection and light manual calls, but once a workflow depends on streaming or binary payloads, move to generated stubs.

Practical guidance​

  • Prefer gRPC for high-throughput or low-latency integrations.
  • Prefer the HTTP API for simple browser or JSON-only consumers.
  • Always send authorization metadata.
  • Send client name and version metadata from production callers.
  • Keep HTTP/2 enabled end to end.
  • Use generated clients for streaming and bytes-heavy flows.