Crate polyoxide_venue 

polyoxide-venue

The vocabulary every polyoxide crate shares, whichever venue it talks to.

• Class sorts every failure into one of eight classes, and Classify, implemented by every public error type in the workspace, reports an error’s class, whether it is a fault, and how long the server asked the caller to wait. ClassifiedError carries any of them.
• class_for_status, class_for_close_code and class_for_handshake_status are the one status and close-code table, and impl_ws_classification! expands the one socket table for polyoxide_ws::WsError in the venue crate that wraps it.
• parse_retry_after is the one Retry-After parser, and retry_delay lets it only lengthen the client’s own backoff.
• Secret holds a value its Debug never prints, and UnixMillis is the time venues stamp things with.
• wire_enum! and open_enum! declare an enum whose variants each have one wire spelling; a closed one refuses an unknown spelling with UnknownVariant, and an open one keeps it in Other.
• With the decimal feature, positional reads and writes rows sent as bare arrays of decimal strings.
• With the keys feature, MarketKey names one instrument as venue.product:id. Only a product’s KeySpace makes one, so two keys are equal exactly when they name the same instrument; RawKey is text split into its parts and checked by no product yet. Each KeySpace declares its product’s ProductClass, which every key it makes carries.
• With the market feature, the traits a venue’s products implement so market data reads the same on every venue: MarketData, which every product implements, and the capability traits Instruments, Trades, Candles, Funding and EventGroups, each with a Dyn wrapper. The class bundles PerpetualMarket, EventContractMarket and SpotMarket name what every product of a class offers. The traits return the records market data is read into (Instrument, Quote, Book, Trade, Candle, FundingRate and EventGroup), each carrying Extensions, a venue’s own facts on a shared record, one value per type.
• With the trading feature, Trading places and cancels orders, reads open orders, positions and balances, and streams a venue’s acknowledgements and fills as TradingEvents, which begins with a Resync and carries another after every reconnect. It works in OrderRequest, Order, Fill, Position and Balance, with the opaque OrderId, FillId and ClientOrderId, each record carrying Extensions; Extensions::ensure_declared is how a venue refuses an option it does not declare.

By default the crate depends on nothing (on wasm32, only web-time, which reads the browser’s wall clock), so a credential-free socket crate can use it without building an HTTP or signing stack. The enum macros name ::serde, so a crate that invokes them depends on serde itself, with serde’s derive feature for wire_enum!, which derives the two traits; open_enum! implements them by hand.

use polyoxide_venue::{class_for_status, Class};

let class = class_for_status(503).unwrap().with_code("dependency_unavailable");
assert!(class.is_retriable());
assert_eq!(class.code(), Some("dependency_unavailable"));
assert_eq!(class_for_status(451), Some(Class::Restricted));

Modules

positional

Rows a venue sends as bare JSON arrays, with decimals as strings, such as a kline [open_time, "open", "high", ..] or a book level ["price", "quantity"].

Macros

impl_ws_classification

Expands, in the invoking module, to the one socket classification table (AD-15) for polyoxide_ws::WsError: three private functions a venue’s Classify impl calls on its WsError-carrying arm.

open_enum

Declares a set the venue reports and extends over time: a spelling this version does not know is kept verbatim in Other instead of failing the response.

wire_enum

Declares a closed set the client sends: one wire spelling per variant.

Structs

Balance

What the account holds of one asset.

Book

An instrument’s order book at one moment.

Candle

One candle. A venue that samples one price per interval gives only close.

CandleQuery

Which candles to read: their width and the open times they span.

ClassifiedError

An error with its class, from any crate: the one error type a venue-neutral caller handles.

ClientOrderId

The id a caller gives an order, which the venue echoes back or the implementation keeps for the orders it placed.

DuplicateExtension

A value was inserted into Extensions that already held one of its type. An InvalidRequest: the caller’s misuse.

DynCandles

Dyn-compatible wrapper for Candles.

DynEventGroups

Dyn-compatible wrapper for EventGroups.

DynFunding

Dyn-compatible wrapper for Funding.

DynInstruments

Dyn-compatible wrapper for Instruments.

DynMarketData

Dyn-compatible wrapper for MarketData.

DynTrades

Dyn-compatible wrapper for Trades.

DynTrading

Dyn-compatible wrapper for Trading.

EventGroup

An event and every outcome it groups, across its markets.

EventOutcome

One outcome of an event: a key of its own, in one of the event’s markets.

Extensions

Facts only one venue has, carried on a shared record: at most one value of each type, read back by its type.

Fill

One order’s part in a trade.

FillId

The venue’s id for a fill: one order’s part in a trade.

FundingRate

A perpetual’s funding rate: the one now accruing, or one already settled.

Instrument

An instrument a venue lists, and the one record that carries its trading rules: tick size, minimum size and SizeUnit.

Level

One price level of a book.

MarketKey

One instrument’s name, written venue.product:id, such as acme.perp:ABCUSD.

NotListed

The venue’s answer identifies the key as an instrument it does not list. A VenueRefusal, as the venue’s own answer for an unknown instrument is.

Order

An order as the venue reports it.

OrderId

The venue’s id for an order.

OrderRequest

An order to place.

Position

What the account holds of one instrument or outcome.

ProductId

A product’s id: the product of venue.product:id, naming the module that trades the instrument.

Quote

An instrument’s best bid and ask at one moment.

RawKey

A key’s text split into venue, product and id, checked by no product yet.

Secret

A credential or other value that must not reach a log.

Trade

One public trade.

TradeId

A trade’s id at its venue. Opaque: compare it, never parse it.

TradingEvents

The stream Trading::events returns: the account’s acknowledgements and fills, from an unbounded queue.

UndeclaredExtension

A request carried an extension of a type its venue does not declare (Extensions::ensure_declared). An InvalidRequest: the caller’s misuse, refused before anything is sent.

UnixMillis

Milliseconds since the Unix epoch, the unit venues stamp orders and frames with.

UnknownVariant

A string that is not one of a closed set’s wire spellings.

UnservedInterval

A query asked for a candle width the venue does not serve (CandleQuery::ensure_served). An InvalidRequest: the caller’s misuse, refused before anything is sent, and no wait or retry cures it.

VenueId

A venue’s id: the venue of venue.product:id.

Enums

CandleInterval

How long a candle spans. A venue serves some or all of these widths, the ones its Candles::intervals lists, and handles every variant, since the enum is exhaustive: a new width is a breaking change that fails to compile at a venue that does not handle it.

Class

What kind of failure an error is, whichever venue or transport produced it.

KeyError

Why text or a key named no instrument a product could read. Every one is an InvalidRequest: the caller named something no request can carry.

KillReason

Why an order was killed.

Liquidity

Whether a fill took or made liquidity.

OrderStatus

Where an order stands.

ProductClass

What a product trades, which fixes what its shared records mean.

Side

Which side of the book an order, or the taker of a trade, is on.

SizeUnit

What an instrument’s sizes count.

TimeInForce

How long an order rests.

TradingEvent

What Trading::events reports.

Traits

Candles

Candles.

Classify

Implemented by every public error type in the workspace.

EventContractMarket

What every event-contract product offers: MarketData and EventGroups, so a function generic over event contracts needs one bound.

EventGroups

Events that group an event-contract venue’s outcomes.

Funding

A perpetual’s funding.

Instruments

Every instrument a product lists, where one request or a few return them.

KeySpace

A product’s keys. A venue crate implements it once for each product it trades, and its methods are the only way to make a MarketKey.

MarketData

What every product implements: its instruments, quotes and books.

PerpetualMarket

What every perpetual-future product offers: MarketData and Funding, so a function generic over perpetuals needs one bound.

SpotMarket

What every ProductClass::Spot product offers: MarketData, and nothing beyond it, so a function generic over products that trade the asset itself needs one bound.

Trades

Public trades.

Trading

Places, cancels and reconciles orders on one venue, and reports what happens to them.

Functions

class_for_close_code

The class of a socket the server closed, from the close frame’s code.

class_for_handshake_status

The class of a WebSocket upgrade the server refused with an HTTP status.

class_for_status

The class an HTTP error status decides, before any body is read.

parse_retry_after

Reads a Retry-After value as decimal seconds, whole or fractional, capped at clamp.

retry_delay

The delay before the next attempt: the longer of what the server asked for and the client’s own backoff.