The Event-Driven Graph (composition)

What is an Event-Driven Graph and how is it composed?

Minimum requirements

Package	Minimum version
controlplane	0.82.1
router	0.80.0
wgc	0.50.3

An Event-Driven Graph (EDG) is best thought to be an abstract subgraph that facilitates Event-Driven Federated Subscriptions (EDFS). If a subgraph uses or defines any event driven directives (@edfs__request, @edfs__publish, and/or @edfs__subscribe), it will be interpreted to be an Event-Driven Graph.

Definitions

The sourceName argument, including the default value "default", must correspond to an equivalent property in events.sources of the router config.yml.

@edfs__publish

directive @edfs__publish(subject: String!, sourceName: String! = "default") on FIELD_DEFINITION

type edfs__PublishResult {
    success: Boolean!
}

Argument name	Type	Value
subject	String!	The event subject. See subjects.
sourceName	String!	The source name, which identifies the connection in the router config.yaml. If unsupplied, the default value "default" will be used.

@edfs__request

directive @edfs__request(subject: String!, sourceName: String! = "default") on FIELD_DEFINITION

Argument name	Type	Value
subject	String!	The event subject. See subjects.
sourceName	String!	The source name, which identifies the connection in the router config.yaml. If unsupplied, the default value "default" will be used.

@edfs__subscribe

directive @edfs__subscribe(
    subjects: [String!]!, sourceName: String! = "default", streamConfiguration: edfs__StreamConfiguration,
) on FIELD_DEFINITION

input edfs__StreamConfiguration {
    consumerName: String!
    streamName: String!
}

Argument name	Type	Value
subjects	[String!]!	The event subjects (it is possible to subscribe to multiple events). See subjects.
sourceName	String!	The source name, which identifies the connection in the router config.yaml. If unsupplied, the default value "default" will be used.
streamConfiguration	edfs__StreamConfiguration	Configures a stream/consumer for a NATS connection. See Stream and consumer configuration.

Compositional rules

The Event-Driven Graph is an "abstract" subgraph, so it must not define any resolvers. EDGs are also subject to special compositional rules.

Root fields

EDG Root fields must define their respective event directive and a valid response type:

Root type	Directive	Response type
Query	@edfs__request	A non-nullable entity object
Mutation	@edfs__publish	edfs__PublishResult!
Subscription	@edfs__susbcribe	A non-nullable entity object

Note that the edfs__StreamConfiguration input object must always be defined to satisfy the @edfs__subscribe directive:

input edfs__StreamConfiguration {
    consumerName: String!
    streamName: String!
}

Here is an example of a valid EDG mutation:

directive @edfs__publish(subject: String!, sourceName: String! = "default") on FIELD_DEFINITION

type Mutation {
    updateUser(
        id: ID!, update: UpdateUserInput!
    ): edfs__PublishResult! @edfs__publish(subject: "updateUser.{{ args.id }}")
}

type edfs__PublishResult {
    success: Boolean!
}

type UpdateUserInput {
    forename: String!
    surname: String!
}

Attempting to return a type other than edfs__PublishResult! from a EDG Mutation root field will result in a compositional error.

Root field arguments and event subjects

Arguments can be defined on a root field, which can then be passed to event subjects through an argument template.

The argument template should follow the period delimiter of your subject. The args refers to the field arguments, which has its own period delimiter, followed by a name of a field argument. This argument name must match exactly to a corresponding field argument name.

eventSubject.{{ args.nameOfAFieldArgument }}

type Subscription {
    # note that the arg template names correspond to the field argument names
    userUpdated(myArgumentName: Int!, another: Int!): User! @edfs__subscribe(
        subjects: ["users.{{ args.myArgumentName }}", "users.{{ args.another }}"]
    )
}

type User @key(fields: "id", resolvable: false) {
    id: @external
}

Entity definitions

EDG entities must be "minimal stubs". This means that only the fields (and nested fields) that form part of its primary key should be included:

1. The primary key must contain the "resolvable" argument set to false.

2. Fields (including nested fields) must form part of the primary key

3. Fields (including nested fields) must be declared @external

Here is an example of a valid EDG entity object definition:

type User @key(fields: "id object { id }", resolvable: false) @external {
 id: Int!
 object: Object!
}

type Object {
 id: Int! @external
}

Other definitions

The EDGs must not define any objects and fields that do not form part of an entity's primary key. Most other definitions are simply ignored, unless, for example, a root field requires an input object.