Flyology Postgres protocol API reference

Description

Abstract byte transports used by the PostgreSQL client and server. Implementations must transfer the complete requested buffer or raise an exception; partial transfers are not exposed to protocol code.

Acquisition_Result

type Acquisition_Result is (Acquired, Need_Acquire_Readiness);

Result of one immediate attempt to acquire the transport capability.

Enumeration literals

Acquired
Need_Acquire_Readiness

Arm_Acquisition

procedure Arm_Acquisition
  (Item      : in out Operation_Transport;
   Operation : in out Flyology.Operations.Operation'Class)

Arm lease and lifecycle readiness on Operation.

Parameters

Item
Operation

Arm_Transport

procedure Arm_Transport
  (Item      : in out Operation_Transport;
   Operation : in out Flyology.Operations.Operation'Class;
   Required  : Step_Result)

Arm the read or write readiness requested by the last step, plus the shared deadline and lifecycle sources.

Parameters

Item
Operation
Required

Cancel_Operation

procedure Cancel_Operation
  (Item : in out Operation_Transport)

Cancel and release every transport borrow before outer cancellation.

Parameters

Item

On_Wait

procedure On_Wait (Item : in out Wait_Observer)

Report that the transfer is waiting for more bytes. Called on the receiving task between transport reads, never concurrently with one, so an implementation may send on the same channel. It must return promptly; time spent here counts against the transfer's deadline.

Parameters

Item: Observer deciding whether it owes the peer anything.

Operation_Transport

type Operation_Transport is limited interface;

Set-independent immediate-step capability used by one outer PostgreSQL operation. Implementations retain their private connection or TLS capability in the concrete transport object; the PostgreSQL operation owns the only Flyology completion-set slot.

Poll_Acquisition

procedure Poll_Acquisition
  (Item   : in out Operation_Transport;
   Result : out Acquisition_Result)

Retry acquisition after the previously armed source becomes ready.

Parameters

Item
Result

Receive_Exactly

procedure Receive_Exactly
  (Item    : in out Transport;
   Data    : out Ada.Streams.Stream_Element_Array;
   Timeout : Duration;
   On_Wait : access Wait_Observer'Class := null)

Fill Data with exactly Data'Length bytes received from Item.

Parameters

Item: Channel from which bytes are read.
Data: Buffer filled before the operation returns.
Timeout: Maximum time allowed for the complete transfer.
On_Wait: Observer notified while the transfer waits. Best effort: a transport that cannot read incrementally, or that never waits, may never call it.

Raised exceptions

Flyology

.IO.Timeout_Error The deadline expires first.

.IO.Device_Error A plaintext peer closes before Data is filled.

.IO.TLS.TLS_Error TLS processing fails or an encrypted peer closes before Data is filled.

Receive_Step

procedure Receive_Step
  (Item   : in out Operation_Transport;
   Data   : out Ada.Streams.Stream_Element_Array;
   Last   : out Ada.Streams.Stream_Element_Offset;
   Result : out Step_Result)

Attempt at most one immediate receive step.

Parameters

Item
Data
Last
Result

Release_Operation

procedure Release_Operation
  (Item : in out Operation_Transport)

Release every transport borrow before the outer operation terminalizes.

Parameters

Item

Send_All

procedure Send_All
  (Item    : in out Transport;
   Data    : Ada.Streams.Stream_Element_Array;
   Timeout : Duration)

Send every byte of Data in array order.

Parameters

Item: Channel to which bytes are written.
Data: Complete buffer to transmit.
Timeout: Maximum time allowed for the complete transfer.

Raised exceptions

Flyology: .IO.Timeout_Error The deadline expires first.

Send_Step

procedure Send_Step
  (Item   : in out Operation_Transport;
   Data   : Ada.Streams.Stream_Element_Array;
   Last   : out Ada.Streams.Stream_Element_Offset;
   Result : out Step_Result)

Attempt at most one immediate send step.

Parameters

Item
Data
Last
Result

Start_Operation

procedure Start_Operation
  (Item      : in out Operation_Transport;
   Operation : in out Flyology.Operations.Operation'Class;
   Result    : out Acquisition_Result;
   Timeout   : Duration)

Begin one transport operation, attempt acquisition once, and arm its shared deadline on Operation.

Parameters

Item
Operation
Result
Timeout

Step_Result

type Step_Result is
  (Made_Progress, Need_Read, Need_Write, Peer_Closed);

Result of one bounded receive or send step.

Enumeration literals

Made_Progress
Need_Read
Need_Write
Peer_Closed

TLS_Upgradable_Transport

type TLS_Upgradable_Transport is limited interface and Transport;

Plain transport that can transfer its underlying channel into TLS.

Transport

type Transport is limited interface;

Bidirectional, blocking byte channel for PostgreSQL wire messages.

Upgrade_TLS

procedure Upgrade_TLS
  (Item        : in out TLS_Upgradable_Transport;
   Backend     : in out Flyology.IO.TLS.Provider'Class;
   Server_Name : String;
   Timeout     : Duration)

Replace Item's plaintext channel with an authenticated TLS connection.

Parameters

Item: Transport to upgrade in place.
Backend: TLS implementation and trust configuration to use.
Server_Name: DNS name checked during certificate verification.
Timeout: Maximum time allowed for the TLS handshake.

Raised exceptions

Flyology: .IO.TLS.TLS_Error The handshake or verification fails.

Wait_Observer

type Wait_Observer is limited interface;

Notified while a transfer waits for its peer. A protocol that owes the peer periodic traffic -- replication feedback, most of all -- would otherwise stay silent for as long as one message takes to arrive, and a message can be large: a primary packs pending WAL into a single XLogData of up to 128 kB. Observing the wait keeps that obligation answerable without letting a partial buffer escape.