API Reference

Warning

This page has been automatically generated as has not yet been reviewed by the authors of dasf-messaging-typescript! Stay tuned for updates and discuss with us at https://codebase.helmholtz.cloud/dasf/dasf-messaging-typescript

`DASFConnection`

The central class for the DASF framework, the connection that is used to create and send messages, and handle their response.

class DASFConnection(urlBuilder, onConnectionError)

Connection to a DASF Backend module via websocket

To create a connection to a remove message broker, provide an instance of DASFUrlBuilder

Example

import { DASFConnection, WebsocketUrlBuilder } from '@dasf/dasf-messaging'
const connection = new DASFConnection(
    new WebsocketUrlBuilder(
        'ws://localhost:8080/ws',
        'some-topic'
    )
)

// send request via the connection and log the response
connection.sendRequest({func_name: 'version_info'}).then(
    (response) => console.log(response)
)

exported from connection

Arguments:

urlBuilder (DASFUrlBuilder) – A builder for the consumer and producer websocket url
onConnectionError ((errorMsg: string) => void) – A callback for the case when no connection could be established

DASFConnection.connected

type: readonly Promise<DASFConnection>

Do something as soon as the websocket connection has been established

This property returns a promise that resolves with the established connection. You can use this to do something right after the connection has been created.

import { DASFConnection, WebsocketUrlBuilder } from '@dasf/dasf-messaging'
const connection = new DASFConnection(
    new WebsocketUrlBuilder(
        'ws://localhost:8080/ws',
        'some-topic'
    )
)

// log to the console when the connection has been connected
connection.connected.then(
    (connection: DASFConnection) => console.log("Websocket connection has been established.")
).catch(
    (error: Error) => console.log(error)
)

async DASFConnection.sendMessage(requestMessage, onProgress)

Send a generic message to the backend module

This low-level implementation takes a generic DASFModuleRequest and sends it to the backend module (as soon as the websocket connection has been established). The result is a promise that resolves to the response of the backend module.

Arguments:

requestMessage (DASFModuleRequest) – The message you want to send
onProgress ((value: { message: DASFProgressReport; props?: object; }) => void) – A callback to use when we receive progress reports while processing the request in the backend module.

Returns:

Promise<DASFModuleResponse> – The promise resolving to the response of the backend module

async DASFConnection.sendRequest(data, onProgress)

Send a request to the backend module and retrieve the response

This high-level implementation of sendMessage() takes an object and sends it as a DASFModuleRequest of type MessageType.Request to the backend module (as soon as the websocket connection has been established). The result is a promise that resolves to the response of the backend module.

Example

import { DASFConnection, WebsocketUrlBuilder } from '@dasf/dasf-messaging'
const connection = new DASFConnection(
    new WebsocketUrlBuilder(
        'ws://localhost:8080/ws',
        'some-topic'
    )
)

// send request via the connection and log the response
connection.sendRequest({func_name: 'version_info'}).then(
    (response) => console.log(response)
)

Arguments:

data (object) – The object that is sent as payload of the request to the backend module
onProgress ((value: { message: DASFProgressReport; props?: object; }) => void) – A callback to use when we receive progress reports while processing the request in the backend module.

Returns:

Promise<unknown> – The promise resolving to the deserialized response of the backend module

DASFConnection.close()

Close all connections

This method closes the connections to the outgoing and incoming websocket.

Example

import { DASFConnection, WebsocketUrlBuilder } from '@dasf/dasf-messaging'
const connection = new DASFConnection(
    new WebsocketUrlBuilder(
        'ws://localhost:8080/ws',
        'some-topic'
    )
)

// send request via the connection and log the response
connection.sendRequest({func_name: 'version_info'}).then(
    (response) => {
      console.log(response)
      // close the connection upon receival
      connection.close()
    }
)

async DASFConnection.getApiInfo()

Get api information for this backend module

This method retrieves the api info, namely the individual JSONSchema representations for the functions and classes in the backend module. Different from getModuleInfo(), this method does not only provide a single JSONSchema, but rather one JSONSchema for each method/function in the backend module.

Returns:: Promise<ModuleApiInfo> – an object representing the api of the backend module.

async DASFConnection.getModuleInfo()

Get information on requests for this module

This method retrieves the JSONSchema representation for requests to this module. It is one large schema object that can be used to validate a request for the sendRequest() method.

Returns:: Promise<JSONSchema7> – A promise that resolves to the JSONSchema for a request to this topic

`DASFUrlBuilder`

A class to build urls to let the DASFConnection connect to a message broker. We have two implemented, the WebsocketUrlBuilder and the PulsarUrlBuilder.

interface DASFUrlBuilder

Interface providing DASF connection urls and parameters

exported from urls

DASFUrlBuilder.DASFConsumerURL

type: string

A url that allows to create a consumer with the DASF web socket api.

DASFUrlBuilder.DASFProducerURL

type: string

See DASFConsumerURL for an explanation.

DASFUrlBuilder.consumeTopic

type: string

The topic on that the consumer listens. Needed to get the results for the backend module.

DASFUrlBuilder.topic

type: string

Which topic is used?

class WebsocketUrlBuilder(websocketUrl, topic, producerUrl='', consumerUrl='')

Url builder for predefined websocket url

exported from urls

Implements:

DASFUrlBuilder

Arguments:

websocketUrl (string)
topic (string)
producerUrl (string)
consumerUrl (string)

WebsocketUrlBuilder.DASFConsumerURL

type: readonly string

A url that allows to create a consumer with the DASF web socket api.

WebsocketUrlBuilder.DASFProducerURL

type: readonly string

See DASFConsumerURL for an explanation.

WebsocketUrlBuilder.consumeTopic

type: readonly string

The topic on that the consumer listens. Needed to get the results for the backend module.

WebsocketUrlBuilder.topic

type: readonly string

Which topic is used?

WebsocketUrlBuilder.buildUrl(websocketUrl, topic)

Arguments:

websocketUrl (string)
topic (string)

Returns:

string

WebsocketUrlBuilder.generateConsumeTopic(topic)

Arguments:

topic (string)

Returns:

string

WebsocketUrlBuilder.generateRequestToken()

Returns:: string

WebsocketUrlBuilder.generateSubscriptionPrefix()

Returns:: string

class PulsarUrlBuilder(host, port, namespace, topic, protocol='ws')

Default url builder for apache pulsar implementation based on host:port, namespace and topic

exported from urls

Implements:

DASFUrlBuilder

Arguments:

host (string)
port (string)
namespace (string)
topic (string)
protocol (string)

PulsarUrlBuilder.DASFConsumerURL

type: readonly string

A url that allows to create a consumer with the DASF web socket api.

PulsarUrlBuilder.DASFProducerURL

type: readonly string

See DASFConsumerURL for an explanation.

PulsarUrlBuilder.consumeTopic

type: readonly string

The topic on that the consumer listens. Needed to get the results for the backend module.

PulsarUrlBuilder.topic

type: readonly string

Which topic is used?

PulsarUrlBuilder.buildUrl(host, port, namespace, type, topic, protocol)

Arguments:

host (string)
port (string)
namespace (string)
type (Type)
topic (string)
protocol (string)

Returns:

string

PulsarUrlBuilder.generateConsumeTopic(topic)

Arguments:

topic (string)

Returns:

string

PulsarUrlBuilder.generateRequestToken()

Returns:: string

PulsarUrlBuilder.generateSubscriptionPrefix()

Returns:: string

Request Message classes 

The following classes represent the messages that are communicated between the client and server stub.

class DASFModuleRequest()

A request to a DASF backend module

This class can be used to create a request that is sent via the message broker to a DASF backend module.

exported from messages

DASFModuleRequest.context

type: string

An identifier for the request to handle identify the response handler

DASFModuleRequest.payload

type: string

The request data.

usually encoded as byte64 string.

DASFModuleRequest.properties?

type: DASFRequestProperties

Properties of the request

the properties of the request may be derived from the PropertyKeys enum.

DASFModuleRequest.getMessageType()

Shortcut to the the messagetype of the properties

Returns:: MessageType

static DASFModuleRequest.createApiInfoMessage()

Shortcut to create an Info message

This static method creates a DASFModuleRequest with the MessageType MessageType.Info to get the information on the backend module, see also DASFConnection.getApiInfo()

Returns:: DASFModuleRequest – The DASFModuleRequest of type MessageType.ApiInfo

static DASFModuleRequest.createInfoMessage()

Shortcut to create an Info message

This static method creates a DASFModuleRequest with the MessageType MessageType.Info to get the information on the backend module, see also DASFConnection.getModuleInfo()

Returns:: DASFModuleRequest – The DASFModuleRequest of type MessageType.Info

static DASFModuleRequest.createPingMessage()

Shortcut to create a Ping message

This static method creates a DASFModuleRequest with the MessageType MessageType.Ping

Returns:: DASFModuleRequest – The DASFModuleRequest of type MessageType.Ping

static DASFModuleRequest.createPongMessage()

Shortcut to create a Pong message

This static method creates a DASFModuleRequest with the MessageType MessageType.Pong

Returns:: DASFModuleRequest – The DASFModuleRequest of type MessageType.Pong

static DASFModuleRequest.createRequestMessage(data)

Shortcut to create a request message

This static method creates a DASFModuleRequest with the MessageType MessageType.Request

Arguments:

data (object) – Optional data as javascript object that will be json-serialized and added as payload to the request.

Returns:

DASFModuleRequest – The DASFModuleRequest of type MessageType.Request

class DASFModuleResponse()

A response of a backend module.

exported from messages

DASFModuleResponse.messageId

type: string

The id of the message assigned by the message broker

DASFModuleResponse.payload

type: string

The response data.

usually encoded as byte64 string.

DASFModuleResponse.properties?

type: DASFResponseProperties

Properties of the response

the properties of the response may be derived from the PropertyKeys enum.

DASFModuleResponse.publishTime

type: string

The time when this message has been published to the message broker.

DASFModuleResponse.getFragmentId()

Get the id of this fragment.

Returns:: number

DASFModuleResponse.getMessageType()

Shortcut to the the messagetype of the properties

Returns:: MessageType

DASFModuleResponse.getNumberOfFragments()

Get the total number of fragments

Returns:: number

DASFModuleResponse.getRequestContext()

Shortcut to the the request context of the properties

Returns:: string

DASFModuleResponse.getRequestMessageId()

Get the original id of the request

Returns:: string

DASFModuleResponse.isFragmented()

Check if the response is fragmented or not.

Returns:: boolean

class DASFProgressReport()

A tree-like structured progress report.

This class can be used to handle a progress report from the backend module. It is submitted to the onProgress callback of the DASFConnection.sendRequest() when a response arrives with the message type MessageType.Progress

exported from messages

DASFProgressReport.children?

type: DASFProgressReport[]

Child reports within the tree

DASFProgressReport.report_id

type: string

ID for the report.

DASFProgressReport.report_type: type: string

DASFProgressReport.status

type: Status

Status of the underlying process.

DASFProgressReport.step_message

type: string

The description of the process.

DASFProgressReport.steps

type: number

The number of subprocesses in this report.

DASFProgressReport.hasError()

Returns:: boolean

DASFProgressReport.hasSuccess()

Returns:: boolean

DASFProgressReport.isComplete()

Returns:: boolean

DASFProgressReport.isRunning()

Returns:: boolean

Data classes 

The following classes are relevant to the ApiInfo, see DASFConnection.getApiInfo().

class ModuleApiInfo()

An model that represants the API of a backend module.

exported from messages

ModuleApiInfo.classes

type: ClassApiInfo[]

The RPC-enabled classes that this module contains.

ModuleApiInfo.functions

type: FunctionApiInfo[]

The RPC-enabled functions that this module contains.

ModuleApiInfo.rpcSchema

type: JSONSchema7

The aggregated JSON schema for an RPC call to this module.

class FunctionApiInfo()

A function in the API suitable for RPC via DASF

exported from messages

FunctionApiInfo.name

type: string

The name of the function that is used as identifier in the RPC.

FunctionApiInfo.returnSchema

type: JSONSchema7

The JSON Schema for the return value.

FunctionApiInfo.rpcSchema

type: JSONSchema7

The JSON Schema for the function.

class ClassApiInfo()

A class in the API suitable for RPC via DASF

exported from messages

ClassApiInfo.methods

type: FunctionApiInfo[]

The list of methods that this class provides.

ClassApiInfo.name

type: string

The name of the class that is used as identifier in the RPC.

ClassApiInfo.rpcSchema

type: JSONSchema7

The JSON Schema for the constructor of the class.

Enums 

Enums are essentially the same as for the python demessaging package, namely we define the Status enum,

Status

export enum Status {
  Success = 'success',
  Error = 'error',
  Running = 'running',
}

PropertyKeys

PropertyKeys

export enum PropertyKeys {
  ResponseTopic = 'response_topic',
  RequestContext = 'requestContext',
  RequestMessageId = 'requestMessageId',
  MessageType = 'messageType',
  SourceTopic = 'source_topic',
  Fragment = 'fragment',
  NumFragments = 'num_fragments',
  Status = 'status',
}

and MessageType

MessageType

export enum MessageType {
  Ping = 'ping',
  Pong = 'pong',
  Info = 'info',
  ApiInfo = 'api_info',
  Request = 'request',
  Response = 'response',
  Log = 'log',
  Progress = 'progress',
}

PropertyKeys

API Reference

DASFConnection

DASFUrlBuilder

Request Message classes

Data classes

Enums

`DASFConnection`

`DASFUrlBuilder`

Request Message classes 

Data classes 

Enums 