Verbs

Defining Verbs

Go

To declare a Verb, write a normal Go function with the following signature, annotated with the Go comment directive //ftl:verb:

//ftl:verb
func F(context.Context, In) (Out, error) { }

eg.

type EchoRequest struct {}

type EchoResponse struct {}

//ftl:verb
func Echo(ctx context.Context, in EchoRequest) (EchoResponse, error) {
  // ...
}

Kotlin

To declare a Verb, write a normal Kotlin function with the following signature, annotated with the Kotlin annotation @Verb:

@Verb
fun F(In): Out { }

eg.

data class EchoRequest
data class EchoResponse

@Verb
fun echo(request: EchoRequest): EchoResponse {
  // ...
}

Java

To declare a Verb, write a normal Java method with the following signature, annotated with the @Verb annotation:

@Verb
public Output f(Input input) { }

eg.

import xyz.block.ftl.Verb;

class EchoRequest {}

class EchoResponse {}

public class EchoClass {
    @Verb
    public EchoResponse echo(EchoRequest request) {
        // ...
    }
}

Schema

In the FTL schema, verbs are declared with their input and output types:

module example {
  data EchoRequest {}
  
  data EchoResponse {}
  
  verb echo(example.EchoRequest) example.EchoResponse
}

Verbs can be exported to make them callable from other modules:

module example {
  export verb echo(example.EchoRequest) example.EchoResponse
}

By default verbs are only visible to other verbs in the same module (see visibility for more information).

Calling Verbs

Go

To call a verb, import the module's verb client ({ModuleName}.{VerbName}Client), add it to your verb's signature, then invoke it as a function. eg.

//ftl:verb
func Echo(ctx context.Context, in EchoRequest, tc time.TimeClient) (EchoResponse, error) {
    out, err := tc(ctx, TimeRequest{...})
}

Verb clients are generated by FTL. If the callee verb belongs to the same module as the caller, you must build the module first (with callee verb defined) in order to generate its client for use by the caller. Local verb clients are available in the generated types.ftl.go file as {VerbName}Client.

Kotlin

To call a verb, import the module's verb client, add it to your verb's signature, then call() it. eg.

import ftl.time.TimeClient
import xyz.block.ftl.Verb

@Verb
fun echo(req: EchoRequest, time: TimeClient): EchoResponse {
  val response = time.call()
  // ...
}

val response = time.call()

Verb clients are generated by FTL. If the callee verb belongs to the same module as the caller, you must manually define your own client:

@VerbClient(name="time")
interface TimeClient {
    fun call(): TimeResponse
}

Java

To call a verb, import the module's verb client, add it to your verb's signature, then call it. eg.

import ftl.time.TimeClient;
import xyz.block.ftl.Verb;

public class EchoClass {
    @Verb
    public EchoResponse echo(EchoRequest request, TimeClient time) {
        TimeResponse response = time.call();
        // ...
    }
}

Verb clients are generated by FTL. If the callee verb belongs to the same module as the caller, you must manually define your own client:

@VerbClient(name="time")
public interface TimeClient {
    TimeResponse call();
}

Schema

In the FTL schema, verb calls are represented by the +calls annotation:

module echo {
  data EchoRequest {}
  
  data EchoResponse {}
  
  verb echo(example.EchoRequest) example.EchoResponse
    +calls time.time
}

module time {
  data TimeRequest {}
  
  data TimeResponse {
    time Time
  }
  
  export verb time(time.TimeRequest) time.TimeResponse
}

The +calls annotation indicates that the verb calls another verb, in this case the time verb from the time module.