Contract atlas

Hrafnsyn gRPC API

A browsable field manual for the live tracking contract: inspect the service surface, understand auth posture, and pull the exact `tracking.proto` clients should compile from.

Download `tracking.proto` Browse services

Package: hrafnsyn.v1
Services: 3
RPC methods: 12
Schemas: 33

Published surface Repo-backed

TrackingIngress Bidirectional ingestion for collectors and external publishers.
TrackingService Query live state, track history, and server-driven update streams.
AuthService Inspect auth requirements, mint tokens, and manage client sessions.

Auth model

Authenticated deployment

Read calls require an access token, and ingestion calls require admin credentials.

1
Use AuthService.GetAuthStatus, Login, and Refresh to bootstrap access tokens.
2
TrackingService expects authenticated clients when API auth is enabled.
3
TrackingIngress is reserved for admin-capable publishers when API auth is enabled.

Quick start

Generate a client fast

Start from the published proto, then use `grpcurl` to verify the deployment before generating a long-lived client SDK.

terminal

curl -fsSL https://hrafnsyn.unixpimps.net/grpc/tracking.proto -o tracking.proto
grpcurl -import-path . -proto tracking.proto \
  hrafnsyn.unixpimps.net hrafnsyn.v1.TrackingService/GetSystemInfo

Imports

Dependency edges

These upstream protobuf definitions are required by the published contract.

google/protobuf/empty.proto google/protobuf/timestamp.proto

Services

Browsable RPC surface

Every card below is generated from the checked-in `proto/hrafnsyn/v1/tracking.proto` contract.

Service

TrackingIngress

Bidirectional ingestion for collectors and external publishers.

StreamObservations
Bidirectional stream

Send a hello, observations, and heartbeats while receiving accepts, acknowledgements, and notices.

StreamObservationsRequest StreamObservationsResponse

Service

TrackingService

Query live state, track history, and server-driven update streams.

GetSystemInfo
Bidirectional stream

Return configured sources plus the current aircraft and vessel counts.

Empty SystemInfo
ListActiveTracks
Bidirectional stream

List active tracks inside the requested activity window.

ListActiveTracksRequest ListActiveTracksResponse
SearchTracks
Bidirectional stream

Search active tracks by callsign, registration, identity, and related labels.

SearchTracksRequest SearchTracksResponse
GetTrack
Bidirectional stream

Fetch one track with route history, route stats, and recent log entries.

GetTrackRequest GetTrackResponse
StreamTrackUpdates
Bidirectional stream

Subscribe to server-sent updates for changed track ids and active counts.

StreamTrackUpdatesRequest TrackUpdate

Service

AuthService

Inspect auth requirements, mint tokens, and manage client sessions.

GetAuthStatus
Bidirectional stream

Report whether auth is required and which user, if any, is already authenticated.

Empty AuthStatus
Login
Bidirectional stream

Exchange a username and password for an access token, refresh token, and session record.

LoginRequest TokenPair
Refresh
Bidirectional stream

Rotate credentials with a refresh token and receive a fresh token pair.

RefreshRequest TokenPair
ListSessions
Bidirectional stream

List the sessions that belong to the authenticated user.

Empty ListSessionsResponse
RevokeSession
Bidirectional stream

Revoke one session and return the revocation timestamp.

RevokeSessionRequest RevocationResponse
RevokeAllSessions
Bidirectional stream

Revoke every session in scope.

Empty RevocationResponse

Schemas

Messages and enums

Expand a type to inspect every field, number, and repeated or `oneof` mode.

Enum

VehicleType

3 values

VEHICLE_TYPE_UNSPECIFIED

0

VEHICLE_TYPE_PLANE

1

VEHICLE_TYPE_VESSEL

2

Message

SourceDescriptor

4 fields

id repeated

string 1

name repeated

string 2

vehicle_type repeated

VehicleType 3

adapter repeated

string 4

Message

Observation

19 fields

vehicle_type repeated

VehicleType 1

identity repeated

string 2

display_name repeated

string 3

callsign repeated

string 4

registration repeated

string 5

country repeated

string 6

category repeated

string 7

status repeated

string 8

destination repeated

string 9

latitude repeated

double 10

longitude repeated

double 11

speed_knots repeated

double 12

heading_degrees repeated

double 13

altitude_feet repeated

int32 14

observed_at repeated

Timestamp 15

raw_payload_json repeated

bytes 16

aircraft_type repeated

string 17

type_description repeated

string 18

wake_turbulence_category repeated

string 19

Message

ObservationEnvelope

2 fields

source repeated

SourceDescriptor 1

observation repeated

Observation 2

Message

ClientHello

3 fields

client_name repeated

string 1

client_version repeated

string 2

requested_source_ids repeated

string 3

Message

Heartbeat

1 fields

sent_at repeated

Timestamp 1

Message

StreamObservationsRequest

3 fields

heartbeat oneof message

Heartbeat 3

observation oneof message

ObservationEnvelope 2

hello oneof message

ClientHello 1

Message

StreamAccepted

2 fields

active_source_ids repeated

string 1

server_version repeated

string 2

Message

ObservationAck

4 fields

source_id repeated

string 1

identity repeated

string 2

track_id repeated

string 3

observed_at repeated

Timestamp 4

Message

StreamNotice

2 fields

code repeated

string 1

message repeated

string 2

Message

StreamObservationsResponse

3 fields

notice oneof message

StreamNotice 3

ack oneof message

ObservationAck 2

accepted oneof message

StreamAccepted 1

Message

UserProfile

4 fields

id repeated

string 1

username repeated

string 2

email repeated

string 3

is_admin repeated

bool 4

Message

SessionInfo

6 fields

id repeated

string 1

current repeated

bool 2

created_at repeated

Timestamp 3

last_used_at repeated

Timestamp 4

expires_at repeated

Timestamp 5

revoked_at repeated

Timestamp 6

Message

AuthStatus

5 fields

auth_required repeated

bool 1

authenticated repeated

bool 2

access_token_ttl_seconds repeated

int32 3

refresh_token_ttl_seconds repeated

int32 4

current_user repeated

UserProfile 5

Message

LoginRequest

2 fields

username repeated

string 1

password repeated

string 2

Message

RefreshRequest

1 fields

refresh_token repeated

string 1

Message

TokenPair

6 fields

access_token repeated

string 1

refresh_token repeated

string 2

access_token_expires_at repeated

Timestamp 3

refresh_token_expires_at repeated

Timestamp 4

session repeated

SessionInfo 5

user repeated

UserProfile 6

Message

ListSessionsResponse

1 fields

sessions repeated

SessionInfo 1

Message

RevokeSessionRequest

1 fields

session_id repeated

string 1

Message

RevocationResponse

3 fields

scope repeated

string 1

session_id repeated

string 2

revoked_at repeated

Timestamp 3

Message

ActiveCounts

3 fields

total repeated

int32 1

planes repeated

int32 2

vessels repeated

int32 3

Message

SystemInfo

2 fields

sources repeated

SourceDescriptor 1

counts repeated

ActiveCounts 2

Message

TrackSummary

21 fields

id repeated

string 1

vehicle_type repeated

VehicleType 2

identity repeated

string 3

latest_source_id repeated

string 4

latest_source_name repeated

string 5

display_name repeated

string 6

callsign repeated

string 7

registration repeated

string 8

country repeated

string 9

category repeated

string 10

status repeated

string 11

destination repeated

string 12

latitude repeated

double 13

longitude repeated

double 14

speed_knots repeated

double 15

heading_degrees repeated

double 16

altitude_feet repeated

int32 17

observed_at repeated

Timestamp 18

aircraft_type repeated

string 19

type_description repeated

string 20

wake_turbulence_category repeated

string 21

Message

ListActiveTracksRequest

2 fields

limit repeated

int32 1

active_window_minutes repeated

int32 2

Message

ListActiveTracksResponse

2 fields

tracks repeated

TrackSummary 1

counts repeated

ActiveCounts 2

Message

SearchTracksRequest

3 fields

query repeated

string 1

limit repeated

int32 2

active_window_minutes repeated

int32 3

Message

SearchTracksResponse

1 fields

tracks repeated

TrackSummary 1

Message

TrackPoint

11 fields

id repeated

string 1

track_id repeated

string 2

source_id repeated

string 3

source_name repeated

string 4

vehicle_type repeated

VehicleType 5

latitude repeated

double 6

longitude repeated

double 7

speed_knots repeated

double 8

heading_degrees repeated

double 9

altitude_feet repeated

int32 10

observed_at repeated

Timestamp 11

Message

RouteStats

2 fields

distance_meters repeated

double 1

observed_seconds repeated

int32 2

Message

GetTrackRequest

3 fields

track_id repeated

string 1

history_hours repeated

int32 2

log_limit repeated

int32 3

Message

GetTrackResponse

4 fields

track repeated

TrackSummary 1

route_points repeated

TrackPoint 2

route_stats repeated

RouteStats 3

log_entries repeated

TrackPoint 4

Message

StreamTrackUpdatesRequest

1 fields

active_window_minutes repeated

int32 1

Message

TrackUpdate

3 fields

track_ids repeated

string 1

counts repeated

ActiveCounts 2

sent_at repeated

Timestamp 3

StreamObservations

GetSystemInfo

ListActiveTracks

SearchTracks

GetTrack

StreamTrackUpdates

GetAuthStatus

Login

Refresh

ListSessions

RevokeSession

RevokeAllSessions