Topics and messages

Topics

Kafka topics are defined in the model/topics.ts file:

export namespace Topics {
	export class queue extends Topic {}
}

Topic and event design

Our philosophy is simple: we want all mutations to system state to be driven by command events, all externally-visible changes to data to be published as change events, and we want total ordering over both commands and changes. In Kafka, that means that all command and change events must be published on a single topic-partition.

In general, that means there is little need to define extra topics. However, it might be useful from time to time. For example, a service might use a topic to queue messages for later retry, provided that at the time of retry it then re-sequences the message back into the main queue.

Schemas

All event schemas are classes that extend from the Message base class, which itself extends from Struct.

A schema defines a set of fields:

export class GenerateTradeConfirm extends CommandEvent {
	AccountId = field(u32);
	EventSummary = field(EventSummary);
	TradeSummary = field(TradeSummary);
	TradeDetails = field(TradeDetails);
}

Fields are declared using the field() function, which accepts a type as its argument.

Unless otherwise specified, fields are mandatory. The .optional() method may be used to make a field optional:

EventSummary = field(EventSummary).optional();

When a field is optional, it will be considered to have a value if the field is present in the body of the struct and its value is not null. If both these conditions are met, then the value must pass the normal validation rules for the field.

Sometimes a type itself also takes arguments. For example, the str type can have a maximum length:

AccountName = field(str(255));

Array types are declared using the array() function:

Notes = field(array(str)); // any number of notes
NotesWithMaxLen = field(array(str), 10); // maximum 10 notes

Sum types are declared using the one_of() function:

Details = field(one_of(ExecutedOrderDetails, RejectedOrderDetails));

There is currently no limit on how many consitituent types a sum type can have, except that it may not contain multiple numeric datatypes.

More details about datatypes.

← Services