Supabase Edge Functions 実践ガイド：@supabase/server・背景タスク・制約の中で本番運用する

supabase functions new hello-world     # supabase/functions/hello-world/index.ts が生成される
supabase start                          # ローカルスタックを起動
supabase functions serve hello-world    # ローカルで実行
supabase functions deploy hello-world   # デプロイ

export default {
  fetch: withSupabase({ auth: ['publishable', 'secret'] }, async (req, ctx) => {
    const { name } = await req.json()

    return Response.json({
      message: `Hello ${name}!`,
    })
  }),
}

curl -i --location --request POST 'http://127.0.0.1:54321/functions/v1/hello-world' \
  --header 'apiKey: <SUPABASE_PUBLISHABLE_KEY>' \
  --data '{"name":"Functions"}'

// 認証済みユーザーのみ（既定）
withSupabase({ auth: 'user' }, handler)

// 認証不要。Webhookやヘルスチェック向け
withSupabase({ auth: 'none' }, handler)

// サーバー間通信（シークレットキー）
withSupabase({ auth: 'secret' }, handler)

// publishable キー
withSupabase({ auth: 'publishable' }, handler)

// ユーザーJWT または シークレットキーのどちらでも受ける
withSupabase({ auth: ['user', 'secret'] }, handler)

interface SupabaseContext {
  supabase: SupabaseClient      // ユーザーにスコープされる。RLSを尊重
  supabaseAdmin: SupabaseClient // 管理クライアント。RLSをバイパス
  userClaims: UserIdentity | null
  jwtClaims: JWTClaims | null
  authMode: AuthMode
}

import { withSupabase } from 'npm:@supabase/server@^1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    // ctx.supabase は呼び出したユーザーのRLSポリシーに自動的にスコープされる
    const { data, error } = await ctx.supabase.from('todos').select()
    if (error) return Response.json({ error: error.message }, { status: 500 })
    return Response.json({ data, email: ctx.userClaims?.email })
  }),
}

[functions.hello-world]
verify_jwt = false

import { Hono } from 'jsr:@hono/hono@^4'

const app = new Hono()

app.get('/hello-world', (c) => {
  return c.json({ message: 'Hello World!' })
})

app.post('/hello-world', async (c) => {
  const { name } = await c.req.json()
  return c.json({ message: `Hello ${name}!` })
})

export default { fetch: app.fetch }

const stripeSecret = Deno.env.get('STRIPE_SECRET_KEY')
if (!stripeSecret) throw new Error('STRIPE_SECRET_KEY is not configured')

# ローカル: supabase/functions/.env（.gitignore へ！）
supabase functions serve --env-file .env.local

# 本番
supabase secrets set --env-file .env
supabase secrets set STRIPE_SECRET_KEY=sk_live_...
supabase secrets list

1. 署名を検証する            ← 偽イベントを弾く
2. イベントIDを一意制約でINSERT ← 二重配送をDBで弾く
3. 即座に 2xx を返す          ← プロバイダのリトライを止める
4. 重い処理は waitUntil へ    ← レスポンス後に続行

create table public.webhook_events (
  -- プロバイダ側のイベントID。これが冪等キー
  event_id text primary key,
  provider text not null,
  received_at timestamptz not null default now(),
  processed_at timestamptz,
  payload jsonb not null
);

alter table public.webhook_events enable row level security;
-- ポリシーを1本も作らない = 誰も読めない。書き込みは service_role のみ

import { withSupabase } from 'npm:@supabase/server@^1'
import type { SupabaseClient } from 'npm:@supabase/supabase-js@^2'
import Stripe from 'npm:stripe'

const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!, {
  // Denoではfetchベースのクライアントを使う
  httpClient: Stripe.createFetchHttpClient(),
})
// 署名検証にはWeb Crypto（SubtleCrypto）ベースのプロバイダを使う
const cryptoProvider = Stripe.createSubtleCryptoProvider()
const webhookSecret = Deno.env.get('STRIPE_WEBHOOK_SECRET')!

export default {
  // Webhookは verify_jwt = false + auth: 'none'。認証は署名検証で行う
  fetch: withSupabase({ auth: 'none' }, async (req, ctx) => {
    const signature = req.headers.get('stripe-signature')
    if (!signature) return new Response('missing signature', { status: 400 })

    const body = await req.text() // 署名検証には生のボディが必要

    let event: Stripe.Event
    try {
      // 非同期版。Denoでは constructEvent ではなくこちらを使う
      event = await stripe.webhooks.constructEventAsync(
        body,
        signature,
        webhookSecret,
        undefined,
        cryptoProvider,
      )
    } catch {
      // 検証失敗の詳細は返さない（攻撃者への情報提供になる）
      return new Response('invalid signature', { status: 400 })
    }

    // 冪等性: 一意制約違反 = 処理済み
    const { error } = await ctx.supabaseAdmin.from('webhook_events').insert({
      event_id: event.id,
      provider: 'stripe',
      payload: event as unknown as Record<string, unknown>,
    })

    if (error) {
      // 23505 = unique_violation。既に受信済みなので 200 を返してリトライを止める
      if (error.code === '23505') return new Response('duplicate', { status: 200 })
      // それ以外は記録できていない = 再送してほしいので 5xx
      return new Response('storage error', { status: 500 })
    }

    // 重い処理はレスポンス後に。プロバイダのタイムアウトを踏まない
    EdgeRuntime.waitUntil(handleEvent(ctx, event))

    return new Response('ok', { status: 202 })
  }),
}

async function handleEvent(ctx: { supabaseAdmin: SupabaseClient }, event: Stripe.Event) {
  try {
    switch (event.type) {
      case 'checkout.session.completed':
        // 業務処理
        break
      default:
        break
    }
    await ctx.supabaseAdmin
      .from('webhook_events')
      .update({ processed_at: new Date().toISOString() })
      .eq('event_id', event.id)
  } catch (err) {
    // processed_at が null のまま残る = 再処理対象として可視化される
    console.error(JSON.stringify({ level: 'error', event_id: event.id, message: String(err) }))
  }
}

import { withSupabase } from 'npm:@supabase/server@^1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
    // レスポンスをブロックせずに背景処理を開始する
    EdgeRuntime.waitUntil(asyncLongRunningTask())
    return Response.json({ ok: true })
  }),
}

addEventListener('beforeunload', (ev) => {
  console.log('Function will be shutdown due to', ev.detail?.reason)
  // 状態を保存する / 現在の進捗をログに残す
})

[edge_runtime]
policy = "per_worker"

export default {
  fetch: (req) => {
    const upgrade = req.headers.get('upgrade') || ''

    if (upgrade.toLowerCase() != 'websocket') {
      return Response.json(
        { error: "request isn't trying to upgrade to WebSocket." },
        { status: 400 }
      )
    }

    const { socket, response } = Deno.upgradeWebSocket(req)

    socket.onopen = () => console.log('socket opened')
    socket.onmessage = (e) => {
      console.log('socket message:', e.data)
      socket.send(new Date().toString())
    }
    socket.onerror = (e) => console.log('socket errored:', e.message)
    socket.onclose = () => console.log('socket closed')

    return response
  },
}

const uploadId = crypto.randomUUID()
await Deno.writeFile('/tmp/' + uploadId, req.body)
const zipFile = await Deno.readFile('/tmp/' + uploadId)

supabase/
├── functions/
│   ├── _shared/
│   │   └── types.ts
│   ├── process-ticket/
│   │   ├── index.ts      ← HTTPの受け口だけ
│   │   └── pricing.ts    ← 純粋なロジック
│   └── tests/
│       ├── utils/
│       │   └── supabase_env.ts
│       └── process-ticket/
│           ├── pricing.test.ts
│           └── index.test.ts
├── config.toml
└── deno.json

// supabase/functions/process-ticket/pricing.ts — 純粋。I/Oなし
export interface TicketInput {
  readonly basePriceJpy: number;
  readonly quantity: number;
  readonly isMember: boolean;
}

const MEMBER_DISCOUNT_RATE = 0.1;

/** 合計金額を計算する。丸めは切り捨てで統一（会計側と一致させる） */
export function calculateTotalJpy(input: TicketInput): number {
  if (!Number.isInteger(input.quantity) || input.quantity < 1) {
    throw new RangeError("quantity must be a positive integer");
  }
  const subtotal = input.basePriceJpy * input.quantity;
  const discount = input.isMember ? Math.floor(subtotal * MEMBER_DISCOUNT_RATE) : 0;
  return subtotal - discount;
}

// supabase/functions/tests/process-ticket/pricing.test.ts
import { assertEquals, assertThrows } from 'jsr:@std/assert'
import { calculateTotalJpy } from '../../process-ticket/pricing.ts'

Deno.test('会員は10%引きになる（端数は切り捨て）', () => {
  assertEquals(calculateTotalJpy({ basePriceJpy: 1050, quantity: 3, isMember: true }), 2835)
})

Deno.test('数量が0以下なら例外', () => {
  assertThrows(() => calculateTotalJpy({ basePriceJpy: 1000, quantity: 0, isMember: false }))
})

deno test supabase/functions/tests/process-ticket/pricing.test.ts
deno test supabase/functions/tests/process-ticket/index.test.ts --allow-env
deno task test

type LogLevel = 'info' | 'warn' | 'error';

interface LogFields {
  readonly event: string;
  /** 相関ID。1リクエストを横断して追える */
  readonly requestId: string;
  readonly [key: string]: unknown;
}

/** PIIを載せない・1行JSON・レベル付き。この3点だけ守れば後から検索できる */
export function log(level: LogLevel, fields: LogFields): void {
  const line = JSON.stringify({ level, ts: new Date().toISOString(), ...fields });
  // 10,000文字上限を超えると切れるため、超過分は明示的に落とす
  const safe = line.length > 9_500 ? `${line.slice(0, 9_500)}…"truncated":true}` : line;
  if (level === 'error') console.error(safe);
  else if (level === 'warn') console.warn(safe);
  else console.log(safe);
}

name: Deploy Function

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    env:
      SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
      PROJECT_ID: your-project-id

    steps:
      - uses: actions/checkout@v4
      - uses: supabase/setup-cli@v1
        with:
          version: latest
      - run: supabase functions deploy --project-ref $PROJECT_ID

      - uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x
      - run: deno test supabase/functions/tests/ --allow-env
      - run: supabase functions deploy --project-ref $PROJECT_ID