API reference

This is a quick overview of the API surface you’d be interacting with most of the time. There’s also a full API reference available.

dispatch.Func

Define a function, execution of which will be powered by Dispatch.

package main

import (
  "context"
  "log"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  hello := dispatch.Func("hello", func(ctx context.Context, name string) (any, error) {
    log.Printf("Hello, %s", name)
    return nil, nil
  })
}

function.Dispatch

Execute a function asynchronously.

package main

import (
  "context"
  "log"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  hello := dispatch.Func("hello", func(ctx context.Context, name string) (any, error) {
    log.Printf("Hello, %s", name)
    return nil, nil
  })

  hello.Dispatch(context.Background(), "Jane")
}

function.Await

Execute a function asynchronously and wait for its result. Note that Await only works inside another function defined with dispatch.Func.

package main

import (
  "context"
  "log"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  generateGreeting := dispatch.Func("generateGreeting", func(ctx context.Context, name string) (any, error) {
    return fmt.Printf("Hello, %s", name), nil
  })

  hello := dispatch.Func("hello", func(ctx context.Context, name string) (any, error) {
    greeting := generateGreeting.Await(name)
    log.Printf(greeting)

    return nil, nil
  })

  hello.Dispatch(context.Background(), "Jane")
}

function.Gather

Execute the same function asynchronously for each argument.

package main

import (
  "context"
  "log"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  generateGreeting := dispatch.Func("generateGreeting", func(ctx context.Context, name string) (string, error) {
    return fmt.Printf("Hello, %s", name), nil
  })

  hello := dispatch.Func("hello", func(ctx context.Context, names []string) (any, error) {
    greetings := generateGreeting.Gather(ctx, names)

    for _, greeting := range greetings {
      log.Println(greeting)
    }

    return nil, nil
  })

  hello.Dispatch(context.Background(), []string{"Jane", "Mike"})
}

dispatch.New

Initialize Dispatch SDK with a list of functions as arguments.

package main

import (
  "context"
  "log"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  hello := dispatch.Func("hello", func(ctx context.Context, name string) (any, error) {
    log.Printf("Hello, %s", name)
    return nil, nil
  })

  bye := dispatch.Func("bye", func(ctx context.Context, name string) (any, error) {
    log.Printf("Bye, %s", name)
    return nil, nil
  })

  endpoint, err := dispatch.New(hello, bye)
  if err != nil {
    log.Fatal(err)
  }
}

dispatch.ListenAndServe

Start the HTTP server at localhost:8000 and initialize a handler that Dispatch will use to remotely execute functions defined via dispatch.Func.

package main

import (
  "context"
  "log"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  hello := dispatch.Func("hello", func(ctx context.Context, name string) (any, error) {
    log.Printf("Hello, %s", name)
    return nil, nil
  })

  endpoint, err := dispatch.New(hello)
  if err != nil {
    log.Fatal(err)
  }

  if err := endpoint.ListenAndServe(); err != nil {
    log.Fatal(err)
  }
}

endpoint.Handler

Create a handler that Dispatch will use to remotely execute functions defined via dispatch.Func, that is suitable to integrate into an existing HTTP server.

package main

import (
  "context"
  "log"
  "net/http"

  "github.com/dispatchrun/dispatch-go"
)

func main() {
  hello := dispatch.Func("hello", func(ctx context.Context, name string) (any, error) {
    log.Printf("Hello, %s", name)
    return nil, nil
  })

  endpoint, err := dispatch.New(hello)
  if err != nil {
    log.Fatal(err)
  }

  http.Handle(endpoint.Handler())

  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    hello.Dispatch(r.Context(), "Jane")
    w.WriteHeader(http.StatusOK)
  })

  if err := http.ListenAndServe("localhost:8000", nil); err != nil {
    log.Fatal(err)
  }
}

Errors

Each error type instructs Dispatch whether to retry executing a function or not. In addition to retries, different error types can impact the concurrency rate at which Dispatch executes your function. For example, when a function returns ErrThrottled, concurrency rate is decreased to reduce the load on your system. When function starts successfully executing again, concurrency rate is increased back up.

dispatch.ErrTemporary

Retry: Yes.
Concurrency: Decrease.

Function encountered a temporary error that may resolve soon.

dispatch.ErrPermanent

Retry: No.
Concurrency: Increase.

Function encountered a permanent error.

dispatch.ErrTimeout

Retry: Yes.
Concurrency: Decrease.

Function encountered a timeout.

dispatch.ErrThrottled

Retry: Yes.
Concurrency: Decrease.

Function was throttled.

dispatch.ErrUnauthenticated

Retry: No.
Concurrency: Increase.

Function attempted to perform an operation without authentication.

dispatch.ErrPermissionDenied

Retry: No.
Concurrency: Increase.

Function attempted to perform an operation without permission.

dispatch.ErrNotFound

Retry: No.
Concurrency: Increase.

FUnction attempted to access a non-existent resource.

dispatch.ErrInvalidArgument

Retry: No.
Concurrency: Increase.

Function was provided invalid input.

dispatch.ErrInvalidResponse

Retry: No.
Concurrency: Increase.

Function encountered an unexpected response from other part of the system.

dispatch.ErrDNS

Retry: Yes.
Concurrency: Decrease.

Function encountered a DNS error.

dispatch.ErrTCP

Retry: Yes.
Concurrency: Decrease.

Function encountered a TCP error.

dispatch.ErrTLS

Retry: Yes.
Concurrency: Decrease.

Function encountered a TLS error.

dispatch.ErrHTTP

Retry: Yes.
Concurrency: Decrease.

Function encountered an HTTP error.