すべてのメッセージは、この XML スキーマで定義しています。メッセージの形式の表は、このスキーマから書き起こしたものです。
freqrelay-sbe.xml をダウンロード| 項目 | 値 |
|---|---|
package | freqrelay |
| スキーマ ID | 1 |
| version | 1 |
| バイト順 | リトルエンディアン |
コーデックを作る
SBE のコード生成ツールで、このスキーマからエンコードとデコードのコードを作れます。たとえば Real Logic の SBE のツールは、Java、C++、C#、Go、Rust のコードを生成します。
メッセージは小さく、形も固定に近いので、メッセージの形式の表を見て手で書くこともできます。Python サンプルは、struct で手書きしています。
スキーマ
freqrelay-sbe.xml を表示
<?xml version="1.0" encoding="UTF-8"?>
<!--
FreqRelay の配信プロトコル(FIX Simple Binary Encoding)。購読者と FreqRelay の間は UDP で、1 データグラムに 1 メッセージを入れる。
1 データグラムは 1200 バイト以下にする。用語は CONTEXT.md、設計判断は docs/adr/0003、0004、0010 を参照。
購読者は、次の手順で受け取り始める(ADR 0010)。
Hello → Challenge(cookie)→ Authenticate(nonce に cookie を入れた JWT)→ AuthenticateAck(購読者トークン)
→ Subscribe(購読者トークン)→ SubscribeAck → 1 秒ごとに Heartbeat(購読者トークン)→ HeartbeatAck
version 0(Phase1)とは互換性がない。
-->
<sbe:messageSchema xmlns:sbe="http://fixprotocol.io/2016/sbe"
package="freqrelay"
id="1"
version="1"
semanticVersion="0.2.0"
description="FreqRelay tick relay protocol"
byteOrder="littleEndian">
<types>
<composite name="messageHeader" description="Message identifiers and length of the message root">
<type name="blockLength" primitiveType="uint16"/>
<type name="templateId" primitiveType="uint16"/>
<type name="schemaId" primitiveType="uint16"/>
<type name="version" primitiveType="uint16"/>
</composite>
<composite name="groupSizeEncoding" description="Repeating group dimensions">
<type name="blockLength" primitiveType="uint16"/>
<type name="numInGroup" primitiveType="uint16"/>
</composite>
<composite name="varDataEncoding" description="Variable-length data: a length followed by that many bytes">
<type name="length" primitiveType="uint16" maxValue="1024"/>
<type name="varData" primitiveType="uint8" length="0"/>
</composite>
<composite name="Price" description="Fixed-point price: mantissa x 10^exponent">
<type name="mantissa" primitiveType="int64"/>
<type name="exponent" primitiveType="int8" presence="constant">-8</type>
</composite>
<type name="SymbolName" primitiveType="char" length="16" characterEncoding="UTF-8"
description="Symbol name, padded with zero bytes"/>
<type name="SymbolId" primitiveType="uint16" description="Symbol ID assigned by FreqRelay"/>
<type name="OptionalSymbolId" primitiveType="uint16" presence="optional" nullValue="65535"
description="Symbol ID, or null when the symbol does not exist"/>
<type name="UnixNanos" primitiveType="int64" description="UTC time in nanoseconds since 1970-01-01"/>
<type name="RequestId" primitiveType="uint32"/>
<type name="SequenceNumber" primitiveType="uint64"/>
<type name="SubscriberToken" primitiveType="uint8" length="16"
description="Random value that FreqRelay issues on authentication. Valid only from the endpoint that authenticated"/>
<type name="Cookie" primitiveType="uint8" length="16"
description="Short-lived value bound to the endpoint and a time window. Put it in the JWT nonce (URL-safe Base64 without padding)"/>
<type name="HelloPadding" primitiveType="uint8" length="32"
description="Zero bytes that keep Hello larger than Challenge, so that FreqRelay never amplifies a spoofed request"/>
<enum name="BooleanType" encodingType="uint8">
<validValue name="False">0</validValue>
<validValue name="True">1</validValue>
</enum>
<enum name="UpstreamStatus" encodingType="uint8">
<validValue name="Disconnected">0</validValue>
<validValue name="Connecting">1</validValue>
<validValue name="Connected">2</validValue>
</enum>
<enum name="AuthenticateResult" encodingType="uint8">
<validValue name="Accepted" description="The subscriber is created. Send Subscribe with the token">0</validValue>
<validValue name="InvalidCookie" description="The nonce is not a valid cookie for this endpoint (expired, or for another endpoint). Start again from Hello">1</validValue>
<validValue name="MalformedToken" description="The JWT cannot be read, alg is not EdDSA, or a required claim (iss, iat, exp) is missing">2</validValue>
<validValue name="InvalidSignature" description="The signature does not match the public key of the API key">3</validValue>
<validValue name="TokenExpired" description="exp has passed, iat is in the future, or exp - iat exceeds 5 minutes">4</validValue>
<validValue name="AudienceMismatch" description="aud is not the expected value">5</validValue>
<validValue name="UnknownKey" description="The key ID is not known yet. A newly issued key becomes usable within about a minute">6</validValue>
<validValue name="KeyRevoked" description="The API key was revoked (reissued or the contract ended)">7</validValue>
<validValue name="KeyExpired" description="The contract period of the API key has ended">8</validValue>
<validValue name="PlanNotAccepted" description="The plan of the API key is not served by this server">9</validValue>
<validValue name="IpLimitReached" description="The API key already has subscribers on as many IP addresses as its plan allows">10</validValue>
<validValue name="EndpointLimitReached" description="The API key already has the maximum number of subscribers on this IP address">11</validValue>
<validValue name="ServerFull" description="The server has reached its subscriber limit">12</validValue>
<validValue name="RateLimited" description="Too many requests. Retry later">13</validValue>
<validValue name="NotReady" description="The server has not loaded the API keys yet. Retry later">14</validValue>
</enum>
<enum name="SubscribeResult" encodingType="uint8">
<validValue name="Accepted" description="The subscription is replaced with the requested symbols">0</validValue>
<validValue name="UnknownSubscriber" description="The token is not valid from this endpoint. Authenticate again">1</validValue>
</enum>
<enum name="SubscriberEndReason" encodingType="uint8">
<validValue name="None" description="The subscriber is alive">0</validValue>
<validValue name="Unknown" description="FreqRelay does not know the token (for example, after a restart)">1</validValue>
<validValue name="HeartbeatTimeout" description="Heartbeats stopped for too long">2</validValue>
<validValue name="Unsubscribed" description="The subscriber sent an empty Subscribe">3</validValue>
<validValue name="KeyRevoked" description="The API key was revoked">4</validValue>
<validValue name="KeyExpired" description="The contract period of the API key has ended">5</validValue>
<validValue name="Replaced" description="The endpoint authenticated again with another API key">6</validValue>
</enum>
</types>
<sbe:message name="Subscribe" id="1"
description="Subscriber to FreqRelay. Replaces the subscription with the given set of symbols (at most 64). An empty set ends the subscriber.">
<field name="subscriberToken" id="1" type="SubscriberToken"/>
<field name="requestId" id="2" type="RequestId" description="Echoed in SubscribeAck"/>
<group name="symbols" id="3" dimensionType="groupSizeEncoding">
<field name="name" id="4" type="SymbolName"/>
</group>
</sbe:message>
<sbe:message name="SubscribeAck" id="2"
description="FreqRelay to subscriber. When accepted, one entry per requested symbol, in request order. Otherwise no entries.">
<field name="requestId" id="1" type="RequestId"/>
<field name="result" id="2" type="SubscribeResult"/>
<group name="symbols" id="3" dimensionType="groupSizeEncoding">
<field name="symbolId" id="4" type="OptionalSymbolId"/>
<field name="name" id="5" type="SymbolName"/>
</group>
</sbe:message>
<sbe:message name="Heartbeat" id="3"
description="Subscriber to FreqRelay, every second. The subscriber expires after 5 seconds without one.">
<field name="subscriberToken" id="1" type="SubscriberToken"/>
</sbe:message>
<sbe:message name="HeartbeatAck" id="4" description="FreqRelay to subscriber, in reply to each Heartbeat.">
<field name="subscribed" id="1" type="BooleanType"
description="False when the subscriber has ended; authenticate again"/>
<field name="upstreamStatus" id="2" type="UpstreamStatus"/>
<field name="endReason" id="3" type="SubscriberEndReason" description="Why the subscriber ended, when subscribed is False"/>
</sbe:message>
<sbe:message name="Ticks" id="5" description="FreqRelay to subscriber. Ticks of the subscribed symbols.">
<field name="sequence" id="1" type="SequenceNumber"
description="Per-subscriber datagram sequence, starting at 1. A gap means lost datagrams."/>
<group name="ticks" id="2" dimensionType="groupSizeEncoding">
<field name="symbolId" id="3" type="SymbolId"/>
<field name="bid" id="4" type="Price"/>
<field name="ask" id="5" type="Price"/>
<field name="upstreamTime" id="6" type="UnixNanos"/>
<field name="receiveTime" id="7" type="UnixNanos"/>
</group>
</sbe:message>
<sbe:message name="Hello" id="6" description="Client to FreqRelay. Starts authentication. FreqRelay answers with Challenge.">
<field name="padding" id="1" type="HelloPadding"/>
</sbe:message>
<sbe:message name="Challenge" id="7" description="FreqRelay to client, in reply to Hello.">
<field name="cookie" id="1" type="Cookie"/>
</sbe:message>
<sbe:message name="Authenticate" id="8"
description="Client to FreqRelay. A JWT (compact form, ASCII) signed with the API key: alg EdDSA, iss key ID, aud, iat, exp (at most 5 minutes after iat), nonce cookie.">
<field name="requestId" id="1" type="RequestId" description="Echoed in AuthenticateAck"/>
<data name="token" id="2" type="varDataEncoding"/>
</sbe:message>
<sbe:message name="AuthenticateAck" id="9" description="FreqRelay to client, in reply to Authenticate.">
<field name="requestId" id="1" type="RequestId"/>
<field name="result" id="2" type="AuthenticateResult"/>
<field name="subscriberToken" id="3" type="SubscriberToken" description="Zero unless the result is Accepted"/>
</sbe:message>
</sbe:messageSchema>