Struct RestApi 

pub struct RestApi { /* private fields */ }

REST API backend for Vantage — reads data from HTTP JSON endpoints.

Each table maps to an API endpoint: {base_url}/{table_name}. Response shape, paging, filtering and auth are set through RestApi::builder. Table writes return Unsupported errors; send a write with http_request. Cheap to clone: the inner ResilientClient is shared.

Implementations

impl RestApi

pub fn new(base_url: impl Into<String>) -> Self

Create a new REST API pointing at base_url, with every builder default: the ResponseShape::default envelope ({ "data": [...] }) and JSON Server paging params. For other shapes (bare array, wrapped-by-table-name) or auth, use RestApi::builder.

pub fn builder(base_url: impl Into<String>) -> RestApiBuilder

Start configuring a RestApi via the builder.

pub fn total_key(&self) -> Option<&str>

The configured response-envelope total key, if any. When set, the REST shell can report an exact count and serve fetch_window.

pub fn ordering(&self) -> Option<&OrderingParams>

The sort query param, when configured.

pub fn breaker_state(&self) -> Option<BreakerState>

What the circuit breaker is doing right now. None when the underlying client has no breaker configured.

pub fn client(&self) -> &ResilientClient

The resilient client backing this API — the pool, breaker and observer a caller outside the read path (e.g. an outbox replaying a queued write) should share rather than build its own.

pub fn base_url(&self) -> &str

The configured base URL requests are joined against.

pub fn with_bearer_source(&self, source: BearerSource) -> Self

A clone whose requests carry the bearer token source gives at the moment each one goes out, in place of the configured auth. The clone shares this API’s client — connection pool, parallel cap, breaker and observer — so one clone per session costs no extra connections. See BearerSource.

The client adds an auth_refresher’s header itself, so a clone can’t withdraw it: build the shared API without a refresher when its clones bring their own tokens.

pub async fn http_request( &self, method: Method, path: &str, headers: &[(&str, &str)], body: Option<&Value>, ) -> Result<Response>

Issue an arbitrary HTTP request against base_url/path, through the same resilient client and auth header as reads.

headers are applied after the configured Authorization header, so a caller-supplied header of the same name wins. body, when given, is sent as the JSON request body. The call policy follows vantage_core::Priority::current, same as a table read. On success, a non-GET method reports TransportEvent::WritePushed to the observer.

A header name or value that HTTP cannot carry (a newline, say) is an error, returned before anything is sent.

impl RestApi

pub fn vista_factory(&self) -> RestApiVistaFactory

Return a Vista factory bound to this REST API data source.

Trait Implementations

impl Clone for RestApi

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl DataSource for RestApi

impl Debug for RestApi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ExprDataSource<Value> for RestApi

async fn execute(&self, expr: &Expression<CborValue>) -> Result<CborValue>

A bare template is its own text. A lone {} around one value — a deferred read such as column_table_values_expr — evaluates to that value. Anything else has no REST meaning and is null.

fn defer(&self, expr: Expression<CborValue>) -> DeferredFn<CborValue>

fn associate<R>( &self, expr: Expression<T>, ) -> AssociatedExpression<'_, Self, T, R>

where Self: Sized,

Create an associated expression with type-safe return type

impl TableSource for RestApi

fn eq_condition(field: &str, value: &str) -> Result<Self::Condition>

Build a stringy field == value eq-condition. Stringy callers (the model-driven CLI) only have text on hand; values arrive as String and become CBOR text scalars here. The peeling code in condition_to_query_param renders all scalar variants the same way so the URL still reads correctly.

fn eq_value_condition( &self, field: &str, value: Self::Value, ) -> Result<Self::Condition>

Typed-value sibling of eq_condition. Used by Reference::resolve_from_row to push a row-derived join value onto a child table without a string round-trip.

fn in_values_condition( &self, field: &str, values: Vec<Self::Value>, ) -> Result<Self::Condition>

A REST endpoint takes one value per filter param, so a single value becomes the same field = value as eq_value_condition. Any other list is refused: an IN the URL can’t carry would be dropped from the request and widen the set.

fn related_in_condition<SourceE: Entity<Self::Value> + 'static>( &self, target_field: &str, source_table: &Table<Self, SourceE>, source_column: &str, ) -> Self::Condition

where Self: Sized,

Build a child condition for with_many / with_one traversal.

REST APIs can’t run subqueries, so this resolves on two paths:

• Sync peek — if the parent already carries an eq-condition on source_column, we re-key its value onto target_field and we’re done. Covers the common with_many case where source_column is the parent’s id field (narrowed via id=N or [N]).
• Deferred read — otherwise (the with_one case, where source_column is a foreign-key field that lives in the parent’s record, not its conditions), we wrap the resolution in a DeferredFn that fetches the parent at request time and pulls the field out of the row. fetch_records resolves deferreds before peeling conditions into query params.

fn column_table_values_expr<'a, E, Type: ColumnType>( &'a self, table: &Table<Self, E>, column: &Self::Column<Type>, ) -> AssociatedExpression<'a, Self, Self::Value, Vec<Type>>

where E: Entity<Self::Value> + 'static, Self: Sized,

A REST API runs no subqueries, so the column’s values are read by listing the table when the expression is resolved and taking column from each row (rows without it are skipped). Resolves to a CBOR array.

type Column<Type> = Column<Type> where Type: ColumnType

type AnyType = Value

type Value = Value

type Id = String

type Condition = Expression<<RestApi as TableSource>::Value>

The condition type stored by Table. SQL/SurrealDB backends use Expression<Self::Value>; document-oriented backends like MongoDB can use a native filter type (e.g. bson::Document).

type Source = String

How this backend names its source. Most backends use String; SQL/SurrealDB backends use SelectSource<Self::Select> so a table can be sourced from an arbitrary sub-SELECT. See crate::source.

fn describe_condition(&self, condition: &Self::Condition) -> String

condition as text for people, e.g. client_id = 7: what a log entry records for a bulk delete. Not for parsing; use Self::condition_column / Self::condition_equality in code. A part resolved only at query time renders as a placeholder.

fn condition_column(&self, condition: &Self::Condition) -> Option<String>

The column condition narrows to values, for the shapes this backend can read (col = v, col IN (…), comparisons, LIKE), with a value — not a column or an arbitrary expression — on the right. None when it can’t tell — a raw expression, a combination, a negation (!=, NOT IN, NOT LIKE), col = other_col — so a check that requires a condition on some column fails safe.

fn create_column<Type: ColumnType>(&self, name: &str) -> Self::Column<Type>

Create a new column with the given name

fn to_any_column<Type: ColumnType>( &self, column: Self::Column<Type>, ) -> Self::Column<Self::AnyType>

Convert a typed column to type-erased column

fn convert_any_column<Type: ColumnType>( &self, any_column: Self::Column<Self::AnyType>, ) -> Option<Self::Column<Type>>

Attempt to convert a type-erased column back to typed column

fn expr( &self, template: impl Into<String>, parameters: Vec<ExpressiveEnum<Self::Value>>, ) -> Expression<Self::Value>

Create an expression from a template and parameters, similar to Expression::new

fn search_table_condition<E>( &self, _table: &Table<Self, E>, search_value: &str, ) -> Expression<Self::Value>

where E: Entity<Self::Value>,

Create a search condition matching search_value across the columns of Table::search_columns: those flagged Searchable, or every column when none is. A backend may leave out columns it can’t filter on (dotted paths, imported columns). This is a server-side capability — it pushes the match down to the backend’s query engine.

fn list_table_values<'life0, 'life1, 'async_trait, E>( &'life0 self, table: &'life1 Table<Self, E>, ) -> Pin<Box<dyn Future<Output = Result<IndexMap<Self::Id, Record<Self::Value>>>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get all data from a table as Record values with IDs (for ReadableValueSet implementation)

fn get_table_value<'life0, 'life1, 'life2, 'async_trait, E>( &'life0 self, table: &'life1 Table<Self, E>, id: &'life2 Self::Id, ) -> Pin<Box<dyn Future<Output = Result<Option<Record<Self::Value>>>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Get a single record by ID as Record value (for ReadableValueSet implementation).

fn get_table_some_value<'life0, 'life1, 'async_trait, E>( &'life0 self, table: &'life1 Table<Self, E>, ) -> Pin<Box<dyn Future<Output = Result<Option<(Self::Id, Record<Self::Value>)>>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get some data from a table as Record value with ID (for ReadableValueSet implementation)

fn get_table_count<'life0, 'life1, 'async_trait, E>( &'life0 self, table: &'life1 Table<Self, E>, ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get count of records in the table

fn get_table_sum<'life0, 'life1, 'life2, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _column: &'life2 Self::Column<Self::AnyType>, ) -> Pin<Box<dyn Future<Output = Result<Self::Value>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Get sum of a column in the table (returns native value type)

fn get_table_max<'life0, 'life1, 'life2, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _column: &'life2 Self::Column<Self::AnyType>, ) -> Pin<Box<dyn Future<Output = Result<Self::Value>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Get maximum value of a column in the table (returns native value type)

fn get_table_min<'life0, 'life1, 'life2, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _column: &'life2 Self::Column<Self::AnyType>, ) -> Pin<Box<dyn Future<Output = Result<Self::Value>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Get minimum value of a column in the table (returns native value type)

fn insert_table_value<'life0, 'life1, 'life2, 'life3, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _id: &'life2 Self::Id, _record: &'life3 Record<Self::Value>, ) -> Pin<Box<dyn Future<Output = Result<Record<Self::Value>>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Insert a record by ID. Confined and idempotent: when the id is already stored in table.conditions(), return the stored row unchanged; when it is held by a row outside the set, fail with Conflict; a new row must fit the conditions, else Conflict and nothing is stored. Refuse with Unsupported when a condition can be neither applied nor evaluated. See WritableValueSet for the table.

fn replace_table_value<'life0, 'life1, 'life2, 'life3, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _id: &'life2 Self::Id, _record: &'life3 Record<Self::Value>, ) -> Pin<Box<dyn Future<Output = Result<Record<Self::Value>>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Replace a record by ID, creating it when missing. Confined and idempotent: an id held by a row outside table.conditions() fails with Conflict; the written row must fit the conditions, else Conflict and nothing changes. Refuse with Unsupported when a condition can be neither applied nor evaluated. See WritableValueSet for the table.

fn patch_table_value<'life0, 'life1, 'life2, 'life3, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _id: &'life2 Self::Id, _partial: &'life3 Record<Self::Value>, ) -> Pin<Box<dyn Future<Output = Result<Record<Self::Value>>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Merge partial into the row with this ID. Confined: a missing row or one outside table.conditions() is NotFound (marked); the merged row must still fit the conditions, else Conflict and nothing changes. Refuse with Unsupported when a condition can be neither applied nor evaluated. See WritableValueSet for the table.

fn delete_table_value<'life0, 'life1, 'life2, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _id: &'life2 Self::Id, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Delete a record by ID. Confined and idempotent: delete only when the row is in table.conditions(); a missing row or a row outside the set is Ok(()) (no lookup is needed — SQL: DELETE … WHERE id = ? AND <conditions>). Refuse with Unsupported when a condition can be neither applied nor evaluated. See WritableValueSet for the table.

fn delete_table_all_values<'life0, 'life1, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete every record the table represents (for WritableValueSet).

fn insert_table_return_id_value<'life0, 'life1, 'life2, 'async_trait, E>( &'life0 self, _table: &'life1 Table<Self, E>, _record: &'life2 Record<Self::Value>, ) -> Pin<Box<dyn Future<Output = Result<Self::Id>> + Send + 'async_trait>>

where E: Entity<Self::Value> + 'async_trait, Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Insert a record under a generated ID and return it. Confined, not retry-safe: the record must fit table.conditions(), else Conflict and nothing is stored; a retry after a lost reply stores a second row. Refuse with Unsupported when a condition can be neither applied nor evaluated.

fn condition_equality( &self, condition: &Self::Condition, ) -> Option<(String, Self::Value)>

When condition is a literal column = value, return the pair.

fn can_confine_writes(&self) -> bool

Whether every by-id write (insert_table_value, replace_table_value, patch_table_value, delete_table_value, insert_table_return_id_value) honours the write contract over table.conditions(): it only touches rows in the set, and only leaves rows that still belong to it. A source that returns false is refused any by-id write through a conditioned table: Table refuses it with Unsupported before reaching the source. Default false.

fn coerce_reference_value(&self, value: Self::Value) -> Self::Value

Coerce a reference join value into the backend’s native id form.

fn stream_table_values<'a, E>( &'a self, table: &Table<Self, E>, ) -> Pin<Box<dyn Stream<Item = Result<(Self::Id, Record<Self::Value>), VantageError>> + Send + 'a>>

where E: Entity<Self::Value> + 'a, Self: Sized,

Stream all records from a table as (Id, Record) pairs.

fn related_correlated_condition( &self, target_table: &str, target_field: &str, source_table: &str, source_column: &str, ) -> Self::Condition

Build a correlated condition: target_table.target_field = source_table.source_column.

fn supports_traversal(&self) -> bool

Whether this backend can lower a dotted active column ("country.name") into its own query — a nested correlated subquery for SQL, a native idiom path for SurrealDB, $lookup stages for MongoDB. Backends that can build none of these (e.g. CSV, REST) leave the default false, and Table::with_active_columns rejects dotted names against them at build time rather than at fetch time.

fn traversal_path_expr( &self, hops: &[&str], column: &str, ) -> Option<Expression<Self::Value>>

Build a backend-native path expression for a dotted active column, tried before the generic correlated-subquery chain.