A function from an empty directory to Supabase

A Supabase Edge Function written in Dart, step by step: a small REST API over a table of the project, run on a laptop first, then deployed. Every step below was run as written, against the Supabase CLI's local stack; the last step (the deploy to a hosted project) uses the CLI's documented commands and was not.

What you need: the Dart SDK, the Supabase CLI and, for the local stack, Docker.

1. The project

mkdir notes_function && cd notes_function
supabase init                  # makes supabase/config.toml
mkdir -p bin lib/src lib/resources test supabase/migrations

pubspec.yaml:

name: notes_function
publish_to: none

environment:
  sdk: ^3.13.0

dependencies:
  spring_boot_starter_edge: ^0.9.0       # the function, with the web starter
  spring_boot_starter_security: ^0.9.0   # checks the project's tokens
  spring_boot_starter_supabase: ^0.9.0   # the project's tables as repositories

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  test: ^1.33.0
dart pub get

2. The application

bin/main.dart, the whole entry point:

import 'package:spring_boot_starter_edge/spring_boot_starter_edge.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main() => runFetchApplication(() => springApplication);

lib/src/note.dart, a table and its repository:

import 'package:spring_boot_starter_supabase/spring_boot_starter_supabase.dart';

/// A row of the table `notes`.
@Introspected()
@Table('notes')
class Note {
  Note({required this.text, this.id});

  @Id()
  int? id;

  @NotBlank()
  String text;
}

/// The table through the project's REST API, as the caller: the policy of
/// the table decides which rows a user sees.
abstract interface class Notes implements ListCrudRepository<Note, int> {}

lib/src/notes_controller.dart, the endpoints and who may call them:

import 'package:notes_function/src/note.dart';
import 'package:spring_boot_starter_security/spring_boot_starter_security.dart';

@RestController()
class NotesController {
  NotesController(this.notes);

  final Notes notes;

  /// Open to everyone.
  @GetMapping('/health')
  Map<String, Object?> health() => {'status': 'UP'};

  /// The caller's notes.
  @GetMapping('/notes')
  Future<List<Note>> list() => notes.findAll();

  @PostMapping('/notes')
  @ResponseStatus(HttpStatus.created)
  Future<Note> add(@RequestBody() @Valid() Note note) => notes.save(note);

  /// Who calls, as read from the checked token.
  @GetMapping('/me')
  Map<String, Object?> me(Authentication caller) => {'id': caller.name};
}

@Configuration()
class SecurityConfig {
  @Bean()
  SecurityFilterChain api(HttpSecurity http) => http
      .authorizeHttpRequests(
        (auth) => auth
            .requestMatchers('/health')
            .permitAll()
            .anyRequest()
            .authenticated(),
      )
      .sessionManagement(
        (session) =>
            session.sessionCreationPolicy(SessionCreationPolicy.stateless),
      )
      .csrf((csrf) => csrf.disable())
      .oauth2ResourceServer((server) => server.jwt())
      .build();
}

The bearer tokens are the access tokens of the project's users: the Supabase starter gives the resource server the project's keys, issuer and audience. The function writes no rule about whose notes are whose: it passes the caller's token on, and the table's policy decides.

lib/resources/application.yml:

spring:
  application:
    name: notes
  main:
    banner-mode: off
  # In the function these come from the platform; here for `dart run`.
  supabase:
    url: ${SUPABASE_URL:http://127.0.0.1:54321}
    anon-key: ${SUPABASE_ANON_KEY:}

supabase/migrations/20260101000000_notes.sql, the table with its policy:

create table public.notes (
  id bigint generated by default as identity primary key,
  text text not null,
  owner uuid not null default auth.uid()
);

alter table public.notes enable row level security;

create policy own_notes on public.notes
  for all to authenticated
  using (owner = (select auth.uid()))
  with check (owner = (select auth.uid()));

grant select, insert, update, delete on public.notes to authenticated;

Generate the application's code (again after every change of its beans):

dart run build_runner build

3. Run it as a server

The same main on the Dart VM is an ordinary server: the fastest way to write and debug.

SERVER_PORT=8089 dart run bin/main.dart
curl localhost:8089/health        # {"status":"UP"}
curl -i localhost:8089/notes      # 401: no token

4. A test

test/function_test.dart calls the application as the platform does, without a platform:

import 'package:spring_boot_starter_edge/spring_boot_starter_edge.dart';
import 'package:test/test.dart';

import '../bin/spring_gen/main.spring.dart';

void main() {
  final function = FetchApplication(() => springApplication);
  tearDownAll(function.close);

  Future<int> status(String path) async => (await function.fetch(
    FetchRequest('GET', Uri.parse('https://example.com$path')),
  )).status;

  test('health is open, the notes are not', () async {
    expect(await status('/health'), 200);
    expect(await status('/notes'), 401);
  });
}
dart test

5. Run it as a function, locally

Tell the platform that the application checks the tokens itself, in supabase/config.toml. Without it the gateway answers 401 (Missing authorization header) to every request without a token, also to /health:

[functions.notes]
verify_jwt = false

# The local stack only: its functions reach the project at
# http://kong:8000, while its tokens name the address the clients use.
[edge_runtime.secrets]
SPRING_SUPABASE_AUTH_ISSUER = "http://127.0.0.1:54321/auth/v1"

Build the function into supabase/functions/notes/, then start the stack (the stack must find the function when it starts; after the first time a new build is picked up without a restart, once the instance that served the old one has gone idle, about half a minute):

dart run spring_boot_starter_edge:build --platform supabase --name notes
supabase start

supabase start prints the address and the keys; supabase status prints them again. With the anon key in ANON_KEY:

URL=http://127.0.0.1:54321
curl $URL/functions/v1/notes/health

# A user of the project, and their access token.
TOKEN=$(curl -s "$URL/auth/v1/signup" -H "apikey: $ANON_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "password": "correct horse"}' | jq -r .access_token)

curl $URL/functions/v1/notes/me -H "Authorization: Bearer $TOKEN"
curl $URL/functions/v1/notes/notes -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"text": "first"}'      # 201
curl $URL/functions/v1/notes/notes -H "Authorization: Bearer $TOKEN"

The name of the function (notes) is the first segment of its address and not part of the mappings: @GetMapping('/health') answers /functions/v1/notes/health. Another user who asks for the notes gets an empty list: the policy of the table, not the function, hides them.

The function's log (its start, what the starter warns about, the errors) is the log of the stack's Edge Runtime: docker logs -f supabase_edge_runtime_<project id>.

Add supabase/functions/notes/ to .gitignore: it is built, not written.

6. Deploy it

supabase login
supabase link --project-ref <ref>          # <ref>.supabase.co

supabase db push                           # the migration of step 2
dart run spring_boot_starter_edge:build --platform supabase --name notes
supabase functions deploy notes
curl https://<ref>.supabase.co/functions/v1/notes/health

A hosted project needs nothing of [edge_runtime.secrets]: there the functions and the tokens name the same address. What the application reads from its environment besides the project's own variables is a secret of the project: supabase secrets set NAME=value.

To deploy on every push instead:

dart run spring_boot_starter_edge:workflow --platform supabase --name notes

writes .github/workflows/deploy-notes.yml; give the repository the secrets SUPABASE_ACCESS_TOKEN and SUPABASE_PROJECT_REF.

What next