httk.serve.dsp¶

Serve the DSP 2025-1 minimal public-catalogue profile.

Submodules¶

Attributes¶

`CallbackSender`
`CallbackTransportError`
`DefaultCallbackSender`
`callback_url`
`DCAT_MEDIA_TYPE`	Full media type of the built-in alternate catalogue representation.
`DCAT_PROFILE`	DCAT-AP profile parameter used by the built-in alternate representation.
`DCAT_AP_3_0_1_PROFILE`
`DCAT_AP_MINIMAL_CONTENT_NEGOTIATION`
`DCAT_AP_MINIMAL_PROFILE`
`DSP_2025_1_SPECIFICATION`
`DSP_CONTEXT`	Protected official DSP JSON-LD context required by the 2025-1 schemas.
`DSP_MINIMAL_PROFILE`
`DSP_VERSION`	Implemented Data Space Protocol version.
`EU_FILE_TYPE_CSV`
`EU_FILE_TYPE_JSON`
`HTTP_ENDPOINT_TYPE`	Official DSP endpoint type used by HTTPS-pull data addresses.
`IANA_MEDIA_TYPE_CSV`
`IANA_MEDIA_TYPE_JSON`
`SPDX_SHA256`
`JsonValue`	An arbitrary JSON value modelled with ordinary mutable containers.
`UtcClock`
`UuidFactory`

Exceptions¶

`DspProtocolError`	Represent a protocol failure that an HTTP adapter can serialize directly.
`DspTransitionSuperseded`	Report that a callback was delivered but a concurrent transition won the commit.

Classes¶

`DspCataloguePolicy`	Define the replaceable publication-profile part of a DSP provider.
`DspCatalogueRepresentation`	Describe one selected HTTP representation of a catalogue response.
`MinimalDspCataloguePolicy`	Implement the built-in stable DSP minimal catalogue profile.
`DspDatasetPublication`	Attach the one DSP-specific offer identifier to a neutral dataset.
`DspProviderConfig`	Configure global DSP minimal service and catalogue metadata.
`DspPublicationEntry`	Non-OPTIMADE logical family for durable DSP publication records.
`DspPublicationRecord`	Store exactly one dataset publication or catalogue service envelope.
`AgreementRecord`	Record the provider-created agreement associated with a negotiation.
`CatalogueProfile`	Describe the immutable multi-dataset catalogue served by this provider.
`DataServiceProfile`	Describe the single service through which the dataset is delivered.
`DatasetProfile`	Group one dataset with its DSP offer, distribution, and data address.
`DcatDataServiceProfile`	Describe a public API included only in the owned DCAT projection.
`DeliveryStatus`	Describe delivery health without claiming an unacknowledged DSP transition.
`DistributionProfile`	Describe the one pull distribution for the provider dataset.
`NegotiationRecord`	Record an in-memory contract negotiation and its acknowledged state.
`OfferProfile`	Describe the one static, unconditional offer exposed by the provider.
`TransferRecord`	Record an in-memory transfer process and its acknowledged state.
`DspProvider`	Serve a live dataset catalogue and manage non-durable DSP processes.

Functions¶

create_dsp_app(provider, *[, debug])

Create a mountable serving application for one DSP provider.

Package Contents¶

httk.serve.dsp.create_dsp_app(provider, *, debug=False)[source]¶

Create a mountable serving application for one DSP provider.

Routes, methods, body schemas, status codes, and media types are loaded from the packaged OpenAPI 3.1 contract. Request and response validation resolves only the packaged offline schema registry.

Parameters:

provider (httk.serve.dsp.provider.DspProvider) – In-memory provider whose business operations are exposed.
debug (bool) – Whether Starlette debug responses are enabled for unexpected failures.

Returns:

Mountable serving application with the provider on app.state.

Raises:

TypeError – If provider is not a DspProvider.
RuntimeError – If the packaged contract uses an unsupported construct.

Return type:

httk.serve.http.ServeApp

httk.serve.dsp.CallbackSender[source]¶

httk.serve.dsp.CallbackTransportError[source]¶

httk.serve.dsp.DefaultCallbackSender[source]¶

httk.serve.dsp.callback_url[source]¶

httk.serve.dsp.DCAT_MEDIA_TYPE = 'application/ld+json; profile="https://semiceu.github.io/DCAT-AP/releases/3.0.1/"'[source]¶: Full media type of the built-in alternate catalogue representation.

httk.serve.dsp.DCAT_PROFILE = 'https://semiceu.github.io/DCAT-AP/releases/3.0.1/'[source]¶: DCAT-AP profile parameter used by the built-in alternate representation.

class httk.serve.dsp.DspCataloguePolicy[source]¶

Bases: Protocol

Define the replaceable publication-profile part of a DSP provider.

Implementations own catalogue snapshot requirements, catalogue and dataset serialization, offer serialization, filter policy, and selection of an optional alternate catalogue representation. The provider continues to own live publication retrieval and all DSP negotiation and transfer mechanics.

build_profile(config, publications)[source]¶

Build and validate one immutable live catalogue snapshot.

validate_catalogue_request(config, message)[source]¶

Validate profile-specific catalogue request constraints.

select_catalogue_representation(config, accept)[source]¶

Select the catalogue HTTP representation for an Accept field.

serialize_catalogue(profile, *, alternate)[source]¶

Serialize one catalogue snapshot in the selected projection.

serialize_dataset(profile)[source]¶

Serialize one dataset root response.

serialize_offer(offer, *, include_target)[source]¶

Serialize an offer consistently for catalogues and negotiations.

class httk.serve.dsp.DspCatalogueRepresentation[source]¶

Describe one selected HTTP representation of a catalogue response.

Parameters:

media_type – Exact response media type declared by the DSP OpenAPI contract.
alternate – Whether the policy should render its alternate catalogue projection.
headers – Additional response headers as immutable name-value pairs.

media_type: str¶

alternate: bool = False¶

headers: tuple[tuple[str, str], Ellipsis] = ()¶

class httk.serve.dsp.MinimalDspCataloguePolicy[source]¶

Implement the built-in stable DSP minimal catalogue profile.

build_profile(config, publications)[source]¶

Build and cross-validate the built-in immutable snapshot.

validate_catalogue_request(config, message)[source]¶

Reject catalogue filtering in the built-in minimal profile.

select_catalogue_representation(config, accept)[source]¶

Apply the built-in exact alternate-representation negotiation rule.

serialize_catalogue(profile, *, alternate)[source]¶

Serialize the built-in DSP or context-substituted catalogue.

serialize_dataset(profile)[source]¶

Serialize one built-in DSP dataset document.

serialize_offer(offer, *, include_target)[source]¶

Serialize one built-in unconditional-use offer.

httk.serve.dsp.DCAT_AP_3_0_1_PROFILE = 'https://semiceu.github.io/DCAT-AP/releases/3.0.1/'[source]¶

httk.serve.dsp.DCAT_AP_MINIMAL_CONTENT_NEGOTIATION = 'https://schemas.httk.org/profiles/dsp/2025-1/minimal#dcat-ap-content-negotiation'[source]¶

httk.serve.dsp.DCAT_AP_MINIMAL_PROFILE = 'https://schemas.httk.org/profiles/dcat-ap/3.0.1/minimal'[source]¶

httk.serve.dsp.DSP_2025_1_SPECIFICATION = 'https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1-err1/'[source]¶

httk.serve.dsp.DSP_CONTEXT = 'https://w3id.org/dspace/2025/1/context.jsonld'[source]¶: Protected official DSP JSON-LD context required by the 2025-1 schemas.

httk.serve.dsp.DSP_MINIMAL_PROFILE = 'https://schemas.httk.org/profiles/dsp/2025-1/minimal'[source]¶

httk.serve.dsp.DSP_VERSION = '2025-1'[source]¶: Implemented Data Space Protocol version.

httk.serve.dsp.EU_FILE_TYPE_CSV = 'http://publications.europa.eu/resource/authority/file-type/CSV'[source]¶

httk.serve.dsp.EU_FILE_TYPE_JSON = 'http://publications.europa.eu/resource/authority/file-type/JSON'[source]¶

httk.serve.dsp.HTTP_ENDPOINT_TYPE = 'https://w3id.org/idsa/v4.1/HTTP'[source]¶: Official DSP endpoint type used by HTTPS-pull data addresses.

httk.serve.dsp.IANA_MEDIA_TYPE_CSV = 'https://www.iana.org/assignments/media-types/text/csv'[source]¶

httk.serve.dsp.IANA_MEDIA_TYPE_JSON = 'https://www.iana.org/assignments/media-types/application/json'[source]¶

httk.serve.dsp.SPDX_SHA256 = 'https://spdx.org/rdf/terms#checksumAlgorithm_sha256'[source]¶

class httk.serve.dsp.DspDatasetPublication(dataset, offer_id=None)[source]¶

Attach the one DSP-specific offer identifier to a neutral dataset.

The dataset owns its distribution metadata. The minimal DSP profile accepts exactly one downloadable distribution and infers its CSV or JSON format/media-type IRIs only when either is absent. Other representations must provide both IRIs in the neutral distribution. No file is opened, measured, or hashed by this envelope.

dataset: httk.core.DatasetRecord¶

offer_id: str | None = None¶

property distribution: httk.core.DatasetDistribution¶

Return the sole neutral distribution accepted by this profile.

property distribution_id: str¶

Return the declared distribution IRI or the profile default.

property file_format: str¶

Return the explicit or CSV/JSON-inferred EU file-type IRI.

property media_type: str¶

Return the explicit or CSV/JSON-inferred IANA media-type IRI.

property access_url: str¶

Return the sole distribution’s validated HTTPS access URL.

property byte_size: int | None¶

Return publisher-supplied size metadata from the distribution.

property sha256: str | None¶

Return publisher-supplied checksum metadata from the distribution.

classmethod create(obj)[source]¶

class httk.serve.dsp.DspProviderConfig[source]¶

Configure global DSP minimal service and catalogue metadata.

public_base_url: str¶

service_id: str¶

service_title: str¶

participant_id: str¶

catalog_id: str¶

catalog_title: str¶

catalog_description: str¶

dsp_mount: str = '/dsp'¶

automatic_progression: bool = True¶

dcat_ap_content_negotiation: bool = False¶

dsp_profile: str = 'https://schemas.httk.org/profiles/dsp/2025-1/minimal'¶

dcat_ap_profile: str = 'https://schemas.httk.org/profiles/dcat-ap/3.0.1/minimal'¶

dcat_ap_content_negotiation_profile: str = 'https://schemas.httk.org/profiles/dsp/2025-1/minimal#dcat-ap-content-negotiation'¶

property connector_root_url: str¶

Return the externally visible DSP connector root.

property service_endpoint_url: str¶

Return the externally visible versioned DSP endpoint.

resolve_access_url(access_url)[source]¶

Resolve one validated publication URL against the public origin.

class httk.serve.dsp.DspPublicationEntry[source]¶

Non-OPTIMADE logical family for durable DSP publication records.

type = 'dsp-publications'¶

definition_id = None¶

class httk.serve.dsp.DspPublicationRecord(dataset=None, service=None)[source]¶

Store exactly one dataset publication or catalogue service envelope.

dataset: DspDatasetPublication | None = None¶

service: httk.core.ServiceRecord | None = None¶

classmethod create(obj)[source]¶

class httk.serve.dsp.AgreementRecord[source]¶

Record the provider-created agreement associated with a negotiation.

Parameters:

id – Unique agreement identifier in urn:uuid: form.
policy – Immutable agreement policy JSON.
target – Dataset identifier covered by the agreement.
assigner – Provider participant identifier.
assignee – Consumer participant identifier.
timestamp – UTC XML Schema date-time at which the agreement was created.

id: str¶

policy: collections.abc.Mapping[str, httk.serve.jsondata.FrozenJsonValue]¶

target: str¶

assigner: str¶

assignee: str¶

timestamp: str¶

class httk.serve.dsp.CatalogueProfile[source]¶

Describe the immutable multi-dataset catalogue served by this provider.

Parameters:

id – Stable catalogue identifier.
title – Human-readable catalogue title.
description – Human-readable catalogue description.
participant_id – Provider participant identifier.
dcat_ap_profile – Configured minimal DCAT-AP profile IRI.
datasets – Dataset publication profiles in stable declaration order.
dcat_data_services – Additional public APIs for the DCAT projection.

id: str¶

title: str¶

description: str¶

participant_id: str¶

dcat_ap_profile: str¶

datasets: tuple[DatasetProfile, Ellipsis]¶

dcat_data_services: tuple[DcatDataServiceProfile, Ellipsis]¶

class httk.serve.dsp.DataServiceProfile[source]¶

Describe the single service through which the dataset is delivered.

Parameters:

id – Stable data-service identifier.
title – Human-readable service title.
endpoint_url – HTTPS endpoint used for data delivery.

id: str¶

title: str¶

endpoint_url: str¶

conforms_to: tuple[str, Ellipsis]¶

serves_dataset_ids: tuple[str, Ellipsis]¶

class httk.serve.dsp.DatasetProfile[source]¶

Group one dataset with its DSP offer, distribution, and data address.

Parameters:

dataset – Protocol-neutral dataset metadata.
offer – Unconditional ODRL use offer for this dataset.
distribution – Pull distribution advertised for this dataset.
data_service – Service embedded in the distribution.
data_address – Immutable pull address returned for authorized transfers.

dataset: httk.core.Dataset¶

offer: OfferProfile¶

distribution: DistributionProfile¶

data_service: DataServiceProfile¶

data_address: collections.abc.Mapping[str, httk.serve.jsondata.FrozenJsonValue]¶

class httk.serve.dsp.DcatDataServiceProfile[source]¶

Describe a public API included only in the owned DCAT projection.

Parameters:

id – Stable service identifier.
title – Human-readable service title.
endpoint_url – Public HTTPS API endpoint.
conforms_to – Technical standards implemented by the service.
serves_dataset_ids – Catalogue dataset identifiers served by the API.
endpoint_description – Optional IRI describing the API interface.

id: str¶

title: str¶

endpoint_url: str¶

conforms_to: tuple[str, Ellipsis]¶

serves_dataset_ids: tuple[str, Ellipsis]¶

endpoint_description: str | None¶

class httk.serve.dsp.DeliveryStatus[source]¶

Describe delivery health without claiming an unacknowledged DSP transition.

Parameters:

last_error – Most recent callback failure, if any.
retry_count – Number of delivery attempts made for the last callback.
out_of_sync – Whether the remote peer may not have the acknowledged local state.

last_error: str | None = None¶

retry_count: int = 0¶

out_of_sync: bool = False¶

class httk.serve.dsp.DistributionProfile[source]¶

Describe the one pull distribution for the provider dataset.

Parameters:

id – Stable distribution identifier.
format – DSP transfer format advertised for the distribution.
access_url – HTTPS URL from which data are pulled.
data_service – Embedded service description for DSP catalogue output.

id: str¶

format: str¶

file_format: str¶

media_type: str¶

access_url: str¶

data_service: DataServiceProfile¶

byte_size: int | None = None¶

sha256: str | None = None¶

exception httk.serve.dsp.DspProtocolError(kind, status_code, detail, *, code=None, provider_pid=None, consumer_pid=None)[source]¶

Bases: Exception

Represent a protocol failure that an HTTP adapter can serialize directly.

Parameters:

kind (ErrorKind) – DSP area whose official error document must be emitted.
status_code (int) – HTTP status suitable for the adapter response.
detail (str) – Safe human-readable failure detail.
code (str | None) – Optional machine-readable DSP error code.
provider_pid (str | None) – Provider process identifier, when one is known.
consumer_pid (str | None) – Consumer process identifier, when one is known.

kind¶

status_code¶

detail¶

code = None¶

provider_pid = None¶

consumer_pid = None¶

as_document()[source]¶

Serialize this failure as the official DSP JSON error document.

Returns:: Error document for the exception’s DSP area.
Return type:: dict[str, httk.serve.jsondata.JsonValue]

exception httk.serve.dsp.DspTransitionSuperseded[source]¶

Bases: RuntimeError

Report that a callback was delivered but a concurrent transition won the commit.

This is not a protocol error: by the time it is raised the peer callback has already been delivered successfully, and only the local commit lost a race with a concurrent state transition. There is nothing to report on the wire and no HTTP status to carry, so it deliberately does not subclass DspProtocolError.

type httk.serve.dsp.JsonValue = JsonScalar | list['JsonValue'] | dict[str, 'JsonValue'][source]¶: An arbitrary JSON value modelled with ordinary mutable containers.

class httk.serve.dsp.NegotiationRecord[source]¶

Record an in-memory contract negotiation and its acknowledged state.

Parameters:

provider_pid – Provider process identifier.
consumer_pid – Consumer process identifier.
callback_address – Consumer callback base URL.
state – Last state acknowledged by both protocol processing and callback delivery.
policy – Immutable message offer accepted for the negotiation.
agreement – Created agreement after an agreement callback is acknowledged.
pending_transition – Reserved transition token, if a callback is currently in flight.
delivery – Local delivery health for the latest callback.

provider_pid: str¶

consumer_pid: str¶

callback_address: str¶

state: str¶

policy: collections.abc.Mapping[str, httk.serve.jsondata.FrozenJsonValue]¶

agreement: AgreementRecord | None = None¶

pending_transition: str | None = None¶

delivery: DeliveryStatus¶

class httk.serve.dsp.OfferProfile[source]¶

Describe the one static, unconditional offer exposed by the provider.

Parameters:

id – Stable offer identifier.
target – Dataset identifier to which a message offer must refer.

id: str¶

target: str¶

class httk.serve.dsp.TransferRecord[source]¶

Record an in-memory transfer process and its acknowledged state.

Parameters:

provider_pid – Provider transfer-process identifier.
consumer_pid – Consumer transfer-process identifier.
callback_address – Consumer callback base URL.
agreement_id – Finalized agreement authorizing this transfer.
format – Requested transfer format.
state – Last state acknowledged by both protocol processing and callback delivery.
pending_transition – Reserved transition token, if a callback is currently in flight.
delivery – Local delivery health for the latest callback.

provider_pid: str¶

consumer_pid: str¶

callback_address: str¶

agreement_id: str¶

format: str¶

state: str¶

pending_transition: str | None = None¶

delivery: DeliveryStatus¶

class httk.serve.dsp.DspProvider(config, *, store=None, publications=None, catalogue_policy=None, callback_sender=None, uuid_factory=uuid4, utc_clock=None)[source]¶

Serve a live dataset catalogue and manage non-durable DSP processes.

Business methods accept and return only ordinary JSON dictionaries; a thin HTTP adapter is responsible for route and response-code presentation. All process state is in memory and is lost on restart. Callback transitions are never committed until a peer acknowledges a 2xx response.

Parameters:

config (httk.serve.dsp.config.DspProviderConfig) – Validated fixed provider configuration.
store (httk.store.EntryStore | None) – Caller-owned entry store containing the DSP publication family. Exactly one of store and publications is required.
publications (collections.abc.Iterable[httk.serve.dsp.config.DspPublicationRecord] | None) – Inline dataset and service publication envelopes. Exactly one of publications and store is required.
catalogue_policy (httk.serve.dsp.catalogue.DspCataloguePolicy | None) – Optional replaceable catalogue requirements and serialization policy. The built-in minimal policy is used by default.
callback_sender (httk.serve.dsp.callbacks.CallbackSender | None) – Optional asynchronous callback transport. Supplying one bypasses default network policy and is useful for deterministic tests.
uuid_factory (UuidFactory) – Optional source for provider and agreement identifiers.
utc_clock (UtcClock | None) – Optional UTC clock used for agreement timestamps.

config¶

catalogue_policy¶

property profile: httk.serve.dsp.models.CatalogueProfile¶

Return a freshly validated catalogue snapshot.

automatic_batch()[source]¶

Create a response-local holder for automatic callback actions.

The HTTP adapter uses the returned private holder to release callbacks only from that response’s background hook. Ordinary callers do not need this seam: their automatic callbacks are managed immediately after the business method returns.

Returns:: An empty response-local automatic callback holder.
Return type:: _AutomaticBatch

has_automatic_actions(batch)[source]¶

Report whether a response-local holder has callbacks to release.

Parameters:: batch (_AutomaticBatch) – Holder returned by automatic_batch().
Returns:: Whether the holder contains at least one action.
Return type:: bool

async release_automatic(batch)[source]¶

Start one response’s automatic callbacks after its body was sent.

Parameters:: batch (_AutomaticBatch) – Holder returned by automatic_batch().

async drain_automatic()[source]¶

Wait until all provider-managed automatic callback tasks settle.

async cancel_automatic()[source]¶

Cancel and drain provider-managed automatic callbacks at shutdown.

version_document()[source]¶

Return the DSP 2025-1 HTTPS version-discovery document.

Returns:: Plain DSP protocol-version document.
Return type:: dict[str, httk.serve.dsp.models.JsonValue]

dsp_catalogue(request)[source]¶

Return the DSP catalogue snapshot for an empty catalogue filter.

Parameters:: request (dict[str, object]) – Catalog request message JSON.
Returns:: Plain DSP catalogue document.
Raises:: httk.serve.dsp.models.DspProtocolError – If the request is malformed or filters are unsupported.
Return type:: dict[str, httk.serve.dsp.models.JsonValue]

catalogue(request, representation)[source]¶

Return a catalogue in a representation selected by the policy.

Parameters:

request (dict[str, object]) – Catalog request message JSON.
representation (httk.serve.dsp.catalogue.DspCatalogueRepresentation) – Value returned by select_catalogue_representation().

Returns:

Plain catalogue document.

Return type:

dict[str, httk.serve.dsp.models.JsonValue]

select_catalogue_representation(accept)[source]¶

Select a catalogue response representation through the active policy.

Parameters:: accept (str | None) – Raw HTTP Accept field, or None when absent.
Returns:: Selected representation metadata.
Return type:: httk.serve.dsp.catalogue.DspCatalogueRepresentation

validate_catalogue_request(request)[source]¶

Validate the one unfiltered catalogue request supported by DSP minimal.

dsp_dataset(dataset_id)[source]¶

Return one DSP dataset only when its ID exactly matches.

Parameters:: dataset_id (str) – Requested dataset identifier.
Returns:: Plain DSP dataset document.
Raises:: httk.serve.dsp.models.DspProtocolError – If the identifier is absent or unknown.
Return type:: dict[str, httk.serve.dsp.models.JsonValue]

dcat_catalogue()[source]¶

Return the separate strict owned-context DCAT-AP projection.

Returns:: Plain DCAT-AP-compatible JSON-LD catalogue document.
Return type:: dict[str, httk.serve.dsp.models.JsonValue]

async get_negotiation(provider_pid)[source]¶

Return one acknowledged negotiation process.

Parameters:: provider_pid (str) – Provider negotiation process identifier.
Returns:: Plain DSP negotiation document.
Raises:: httk.serve.dsp.models.DspProtocolError – If the process is unknown.
Return type:: dict[str, httk.serve.dsp.models.JsonValue]

async request_negotiation(message, *, _automatic_batch=None)[source]¶

Accept an initial consumer contract request.

The initial request must omit providerPid, identify the configured offer and dataset exactly, and provide an HTTPS callback. With automatic progression enabled, the agreement callback is scheduled only after the returned process snapshot has been acknowledged to the caller.

Parameters:

message (dict[str, object]) – Contract request message JSON.
_automatic_batch (_AutomaticBatch | None) – Optional response-local holder used by the HTTP adapter.

Returns:

Newly created DSP negotiation document.

Raises:

httk.serve.dsp.models.DspProtocolError – If message validation fails.

Return type:

dict[str, httk.serve.dsp.models.JsonValue]

async counter_request(provider_pid, message)[source]¶

Receive a consumer counter-request after a provider offer.

Parameters:

provider_pid (str) – Provider negotiation process identifier from the route.
message (dict[str, object]) – Consumer contract request message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs, policy, or the transition are invalid.

async negotiation_event(provider_pid, message)[source]¶

Receive the only permitted consumer negotiation event, ACCEPTED.

Parameters:

provider_pid (str) – Provider negotiation process identifier from the route.
message (dict[str, object]) – Contract-negotiation event message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs, event, or transition are invalid.

async verify_agreement(provider_pid, message, *, _automatic_batch=None)[source]¶

Receive consumer verification of an acknowledged agreement.

Parameters:

provider_pid (str) – Provider negotiation process identifier from the route.
message (dict[str, object]) – Agreement-verification message JSON.
_automatic_batch (_AutomaticBatch | None) – Optional response-local holder used by the HTTP adapter.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs, state, or finalization delivery are invalid.

async receive_negotiation_termination(provider_pid, message)[source]¶

Receive consumer termination of a nonterminal negotiation.

Parameters:

provider_pid (str) – Provider negotiation process identifier from the route.
message (dict[str, object]) – Negotiation-termination message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs or the transition are invalid.

async get_transfer(provider_pid)[source]¶

Return one acknowledged transfer process.

Parameters:: provider_pid (str) – Provider transfer-process identifier.
Returns:: Plain DSP transfer-process document.
Raises:: httk.serve.dsp.models.DspProtocolError – If the process is unknown.
Return type:: dict[str, httk.serve.dsp.models.JsonValue]

async request_transfer(message, *, _automatic_batch=None)[source]¶

Accept a consumer pull transfer request under a finalized agreement.

Identical repeated consumer process IDs return the original transfer. A reuse with different agreement, callback, or format is rejected.

Parameters:

message (dict[str, object]) – Transfer request message JSON.
_automatic_batch (_AutomaticBatch | None) – Optional response-local holder used by the HTTP adapter.

Returns:

Newly created or idempotently recovered transfer-process document.

Raises:

httk.serve.dsp.models.DspProtocolError – If request validation or callback delivery fails.

Return type:

dict[str, httk.serve.dsp.models.JsonValue]

async resume_transfer(provider_pid, message)[source]¶

Receive a consumer start message that resumes a suspended transfer.

Parameters:

provider_pid (str) – Provider transfer-process identifier from the route.
message (dict[str, object]) – Transfer-start message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs or the transition are invalid.

async receive_transfer_suspension(provider_pid, message)[source]¶

Receive consumer suspension of a started transfer.

Parameters:

provider_pid (str) – Provider transfer-process identifier from the route.
message (dict[str, object]) – Transfer-suspension message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs or the transition are invalid.

async receive_transfer_completion(provider_pid, message)[source]¶

Receive consumer completion of a started transfer.

Parameters:

provider_pid (str) – Provider transfer-process identifier from the route.
message (dict[str, object]) – Transfer-completion message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs or the transition are invalid.

async receive_transfer_termination(provider_pid, message)[source]¶

Receive consumer termination of a nonterminal transfer.

Parameters:

provider_pid (str) – Provider transfer-process identifier from the route.
message (dict[str, object]) – Transfer-termination message JSON.

Raises:

httk.serve.dsp.models.DspProtocolError – If PIDs or the transition are invalid.

async send_offer(provider_pid)[source]¶

Send a provider contract offer and acknowledge REQUESTED to OFFERED.

Parameters:

provider_pid (str) – Provider negotiation process identifier.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async send_agreement(provider_pid)[source]¶

Send a provider agreement from REQUESTED or ACCEPTED.

Parameters:

provider_pid (str) – Provider negotiation process identifier.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async finalize_negotiation(provider_pid)[source]¶

Send provider finalization after consumer agreement verification.

Parameters:

provider_pid (str) – Provider negotiation process identifier.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async terminate_negotiation(provider_pid, *, code='terminated', reason='negotiation terminated by provider')[source]¶

Send provider termination for any nonterminal negotiation state.

Parameters:

provider_pid (str) – Provider negotiation process identifier.
code (str) – Machine-readable termination code.
reason (str) – Human-readable termination reason.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async start_transfer(provider_pid)[source]¶

Send provider transfer start with the configured pull data address.

Parameters:

provider_pid (str) – Provider transfer-process identifier.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async suspend_transfer(provider_pid, *, code='suspended', reason='transfer suspended by provider')[source]¶

Send provider suspension for a started transfer.

Parameters:

provider_pid (str) – Provider transfer-process identifier.
code (str) – Machine-readable suspension code.
reason (str) – Human-readable suspension reason.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async complete_transfer(provider_pid)[source]¶

Send provider completion for a started transfer.

Parameters:

provider_pid (str) – Provider transfer-process identifier.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

async terminate_transfer(provider_pid, *, code='terminated', reason='transfer terminated by provider')[source]¶

Send provider termination for any nonterminal transfer state.

Parameters:

provider_pid (str) – Provider transfer-process identifier.
code (str) – Machine-readable termination code.
reason (str) – Human-readable termination reason.

Raises:

httk.serve.dsp.models.DspProtocolError – If state or callback delivery is invalid.
httk.serve.dsp.models.DspTransitionSuperseded – If a concurrent transition won the callback commit.

type httk.serve.dsp.UtcClock = Callable[[], datetime][source]¶

type httk.serve.dsp.UuidFactory = Callable[[], UUID | str][source]¶