# Exemplar Project & Cluster
**Author**: safeer
<!-- Status of the document - draft, in-review, etc. - is conveyed via HackMD labels -->

## Description

A full featured exemplar project in the FTL repo that is run in a staging cluster and validated by a smoke test.

## Motivation

We need testable reference implementations of every FTL feature so that the set-up time and complexity of working on any individual feature is reduced.

Locally run smoke tests that verify these features work as intended will increase developer confidence for changes made across the codebase.

The project will also be run in a persistent FTL cluster that serves as a staging environment to allow the upgrade path to be tested and any regressions to be discovered more easily.

## Goals

- Add more useful example code to ftl/examples
- Provide a reference implementation of all FTL features
- Implement a local smoke test that verifies the functionality of all FTL features
- Deploy new versions to a persistent FTL cluster
- Run a smoke test automatically in CI

## Design

### Smoke Test

An FTL cluster with a few modules will live in the `ftl/examples` directory. These modules will implement a contrived example that touches all major FTL features, initiated by a smoke test. This smoke test can be run using a CLI script, or via a Playwright test in the FTL console. Both the CLI script and the Playwright test will provision and run the exemplar cluster locally. CI will run this Playwright test automatically for a full end-to-end validation of `main`.

The smoke test is provided a cluster to run on; either locally created by the CLI or Playwright, or a long running FTL staging cluster. The test first sets a `config` and `secret` value on module `Origin` using `ftl [secret|config] set`, then posts some json to an `HTTP ingress` endpoint via curl. It then waits for a specific console output that indicates data successfully flowed through the examplar cluster.

### Exemplar Project


The exemplar project will include:

- A provisioned database (eventually provisioned automatically)
- Modules written in different languages (Go and Kotlin for now)
- A verb calling an internal (non-exported) verb
- A verb calling an exported verb in a different module
- Various exported FTL types and types in request & response objects
- Types: Int, Float, String, Byte, Bool, Time, Any, Unit, Array, Map, Data Structure, Constant Enumeration
- Type enums (sum types), Value enums, Type aliases, Optional types
- Builtin types: HttpRequest, HttpResponse, Empty, CatchRequest
- FTL features
- HTTP Ingress, Secrets & Config, PubSub, FSM, Retries, Cron, External Types, Unit Tests

### Staging Cluster

A persistent FTL staging cluster is needed to test the upgrade path and discover regressions. The cluster will need to:

- Support upgrading FTL to the latest version in `main`
- Preserve any deployed modules when FTL is upgraded
- Allow new versions of modules to be deployed
- Allow waiting on deployment or determining deployed version
- Allow the smoke test to run and results communicated back

_The details on the staging cluster are fuzzy and will be more concrete within 1-2 weeks as the infra plans pan out. cc @abrooks_

## Required Changes

- __Smoke test script__ that provisions a db, runs the cluster, makes an HTTP POST
- __Origin__ module with HTTP ingress, config+secrets, PubSub publish
- __Relay__ module with PubSub subscribe, FSM transitions, retries, DB write
- __Pulse__ module with Cron job, DB read, verb calls, unit tests
- __Console playwright script__ that automates the smoke test via the console
- __CI end-to-end test__ run the console playwright script automatically
- __Persistent cluster__ (Awaiting infra) create an FTL staging cluster
- __CI upgrade test__ (depends on Persistent Cluster)
- __Mixed language exemplar__ rewrite Relay module in Kotlin