Host-owned SQLite dispatch journal. More...

#include <sqlite_provider_call_broker.h>

Classes
struct	PolicyChange
	A time a call was matched to its record under another descriptor policy identity than the record names (#543). More...

struct	Restart
	A time a resume sent a call that opens a chunked upload's session again, in place of its record (#541). More...

Public Member Functions
ProgramCoreProviderCallBinding	bind (const ProgramCoreProviderCallContext &context, std::string provider_binding_identity)
	The provider identity is the host's immutable deployment/credential-route digest.

ProgramCoreProviderCallBinding	bind_priced (const ProgramCoreProviderCallContext &context, std::string provider_binding_identity)
	bind() that also prices every call against the context's monetary account, as bind_priced_provider_call() does, and keeps the call's ProgramMonetaryRecord in its row with the outcome.

std::vector< PolicyChange >	policy_changes (std::string_view owner_scope, std::string_view dispatch_id) const
	The policy changes noted for one call, oldest first.

void	reconcile_success (std::string_view owner_scope, std::string_view dispatch_id, std::string evidence_identity, sp::runtime::Result completion)
	Only after independent provider-side evidence establishes this exact result.

std::vector< Restart >	restarts (std::string_view owner_scope, std::string_view dispatch_id) const
	The restarts noted for one call, oldest first.

Static Public Member Functions
static std::string	logical_call_id (const ProgramCoreProviderCallContext &context, const graph::ProviderCallIdentity &call)
	Stable across Program attempts; request content is bound to the slot.

Detailed Description

Host-owned SQLite dispatch journal.

Share the journal across resolver calls/runs. A marker means transport MAY have occurred; it does not prove provider receipt or exactly-once execution. Pending/uncertain calls require external reconciliation. A runtime whose resolver returns this journal's brokers should set RuntimeConfig::core_provider_calls_journaled, because only a durable journal lets a fork replay the provider calls of the paused invocation.

Call identity (#543). A call is named by its position (owner, Program version, run, operation, Core thread, task, node and ordinal) and by its request content (Provider::request_content_digest): what the request asks for, not the SchemaProvider descriptor policy that admitted it. The policy's identity (Provider::request_policy_identity) is recorded beside the content. A resume, a crash recovery or a fork that finds the same content under another policy identity replays or adopts the record, notes the change durably (policy_changes()) and reports P_PROVIDER_CALL_POLICY_CHANGED on the run's handle. A different content is a binding conflict on resume and, in a fork, a new call. Rows written before this identity (0.16.0 and earlier; identity version 1) hold only a dispatch digest that includes the policy, so they match only while the policy is unchanged; a fork that cannot tell such a call from a new one is refused (ProgramProviderForkResendRefusedError).

Chunked uploads (#541). The answer to the call that opens an upload's session (PreparedProviderRequest::opens_upload_session()) may carry a value that only the live call may hold: a Google resumable upload's URL, which lets anyone write the file without the API key (Completion::secret). The journal never stores it, and the row says that its answer is short of it (withheld_secret). A resume that finds such a row, or an opening whose answer is not known, cannot give the session back. Where the journal holds no later call of the node's task, nothing was written into the session and opening one charges nothing, so the call is sent again; the row is not rewritten, and the handle carries P_PROVIDER_UPLOAD_RESTARTED. Where it holds one, in any state, the later calls name the first session by the digest of its URL, and the resume fails with ProgramProviderUploadResendRequiredError before anything is sent. A fork sends the opening again, since the source's session is the source's alone. A restart is recorded, in the transaction before the call is sent, in a table of its own (restarts(); Record::restarts and Record::superseded), so the record it replaces stays as it was and a Dispatched record that was restarted does not read as uncertain. The row of such a call carries a marker (Record::opens_upload_session) that lets reconcile_success() refuse an answer a resume could not continue.

Definition at line 160 of file sqlite_provider_call_broker.h.

Member Function Documentation

◆ bind()

ProgramCoreProviderCallBinding neograph::program::SQLiteProgramProviderCallJournal::bind	(	const ProgramCoreProviderCallContext &	context,
		std::string	provider_binding_identity
	)

The provider identity is the host's immutable deployment/credential-route digest.

It must change when any dispatch authority or deployment changes.

◆ bind_priced()

ProgramCoreProviderCallBinding neograph::program::SQLiteProgramProviderCallJournal::bind_priced	(	const ProgramCoreProviderCallContext &	context,
		std::string	provider_binding_identity
	)

bind() that also prices every call against the context's monetary account, as bind_priced_provider_call() does, and keeps the call's ProgramMonetaryRecord in its row with the outcome.

A call this attempt journaled before a restart is charged once, when the restarted attempt binds its operation; a call an earlier attempt journaled was settled by that attempt's result and is never charged again.

◆ policy_changes()

std::vector< PolicyChange > neograph::program::SQLiteProgramProviderCallJournal::policy_changes	(	std::string_view	owner_scope,
		std::string_view	dispatch_id
	)		const

The policy changes noted for one call, oldest first.

A call that was found again under the same policy has none.

◆ reconcile_success()

void neograph::program::SQLiteProgramProviderCallJournal::reconcile_success	(	std::string_view	owner_scope,
		std::string_view	dispatch_id,
		std::string	evidence_identity,
		sp::runtime::Result	completion
	)

Only after independent provider-side evidence establishes this exact result.

The evidence identity is retained, immutable and must not be empty. This method never retries transport; a later invoke replays the verified result.

It refuses (std::runtime_error, nothing written) the record of a call that opens a chunked upload's session (#541) in two cases. A resume sent the call again (Record::superseded, restarts()): a resume restarts or refuses an upload by itself, and the record needs no reconciliation. Or the completion's session names neither an upload id nor a URL: a journal keeps no URL, so a resume would replay a session it cannot continue. A completion that does carry a URL (Completion::secret) is accepted and the URL is not stored; the row then says that its answer is short of it, and a resume restarts the upload.

◆ restarts()

std::vector< Restart > neograph::program::SQLiteProgramProviderCallJournal::restarts	(	std::string_view	owner_scope,
		std::string_view	dispatch_id
	)		const

The restarts noted for one call, oldest first.

They are written in the transaction that precedes the call, so a restart that was recorded was at least about to be sent.

The documentation for this class was generated from the following file:

include/neograph/program/sqlite_provider_call_broker.h

Classes

Public Member Functions