Ecommerce store

Build a small online store in this empty folder with Next.js and deploy it to Volcano.

- Anyone can browse the products without signing in. Seed six products with
  prices, stock counts and images.
- Shoppers sign up with email and password, keep a cart that survives a reload,
  and place orders. No payment provider: placing an order just records it.
- Place each order in a Volcano function, in one transaction: work out the total
  from the prices in the database, take the stock, record the order and empty the
  cart. Never trust a price or total sent from the browser.
- Enforce stock in the database, so two shoppers can't both buy the last unit.
- Keep carts and orders in Postgres with row-level security: each shopper sees
  only their own, and only the function can create orders or change stock.
- Only the anon key goes to the browser, with no more permissions than it needs.

Create a new Volcano project named volcano-shop, deploy to production and give me
the URL. Before you finish, test the live project with two throwaway shoppers:
browsing works signed out; A places an order and sees it; B can't read A's orders;
a forged price or total is ignored or refused; and when A and B order the last
unit at the same time, only one succeeds.

volcano init nextjs
npm install
volcano login
volcano projects create volcano-shop
volcano use volcano-shop
volcano cloud databases create shop --region us-east-1 --pg-version 16

CREATE TABLE IF NOT EXISTS public.products (
  id text PRIMARY KEY CHECK (id ~ '^[a-z0-9-]{1,40}$'),
  name text NOT NULL CHECK (char_length(name) BETWEEN 1 AND 80),
  description text NOT NULL DEFAULT '' CHECK (char_length(description) <= 280),
  price_cents integer NOT NULL CHECK (price_cents > 0),
  stock integer NOT NULL CHECK (stock >= 0),
  image_path text NOT NULL,
  active boolean NOT NULL DEFAULT true,
  created_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS public.cart_items (
  user_id uuid NOT NULL DEFAULT auth.uid(),
  product_id text NOT NULL REFERENCES public.products(id),
  quantity integer NOT NULL CHECK (quantity BETWEEN 1 AND 10),
  PRIMARY KEY (user_id, product_id)
);
CREATE TABLE IF NOT EXISTS public.orders (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id uuid NOT NULL,
  total_cents integer NOT NULL CHECK (total_cents > 0),
  status text NOT NULL DEFAULT 'placed' CHECK (status IN ('placed')),
  created_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS public.order_items (
  order_id uuid NOT NULL REFERENCES public.orders(id),
  user_id uuid NOT NULL,
  product_id text NOT NULL REFERENCES public.products(id),
  product_name text NOT NULL,
  unit_price_cents integer NOT NULL CHECK (unit_price_cents > 0),
  quantity integer NOT NULL CHECK (quantity BETWEEN 1 AND 10),
  PRIMARY KEY (order_id, product_id)
);
CREATE INDEX IF NOT EXISTS orders_user_created_idx ON public.orders (user_id, created_at DESC);
ALTER TABLE public.products ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.cart_items ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.orders ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.order_items ENABLE ROW LEVEL SECURITY;
REVOKE ALL ON public.products, public.cart_items, public.orders, public.order_items
  FROM PUBLIC, anon, authenticated;
GRANT SELECT, DELETE ON public.cart_items TO authenticated;
GRANT INSERT (product_id, quantity) ON public.cart_items TO authenticated;
GRANT UPDATE (quantity) ON public.cart_items TO authenticated;
GRANT SELECT ON public.orders, public.order_items TO authenticated;
DROP POLICY IF EXISTS cart_items_own ON public.cart_items;
CREATE POLICY cart_items_own ON public.cart_items FOR ALL TO authenticated
  USING (user_id = auth.uid()) WITH CHECK (user_id = auth.uid());
DROP POLICY IF EXISTS orders_read_own ON public.orders;
CREATE POLICY orders_read_own ON public.orders FOR SELECT TO authenticated
  USING (user_id = auth.uid());
DROP POLICY IF EXISTS order_items_read_own ON public.order_items;
CREATE POLICY order_items_read_own ON public.order_items FOR SELECT TO authenticated
  USING (user_id = auth.uid());
INSERT INTO public.products (id, name, description, price_cents, stock, image_path) VALUES
  ('lava-mug', 'Lava mug', 'A 12 oz stoneware mug with a glaze that runs like a lava flow.', 1800, 25, '/products/lava-mug.svg'),
  ('obsidian-tee', 'Obsidian tee', 'Heavyweight black cotton tee with a small caldera on the chest.', 2600, 40, '/products/obsidian-tee.svg'),
  ('caldera-hoodie', 'Caldera hoodie', 'Brushed fleece hoodie in ember orange.', 5400, 12, '/products/caldera-hoodie.svg'),
  ('magma-stickers', 'Magma sticker pack', 'Six vinyl stickers for laptops and water bottles.', 600, 100, '/products/magma-stickers.svg'),
  ('ash-cap', 'Ash cap', 'Six-panel cap in volcanic grey, one size.', 2200, 18, '/products/ash-cap.svg'),
  ('eruption-poster', 'Eruption poster', 'A 50 × 70 cm risograph print, signed and numbered.', 3500, 1, '/products/eruption-poster.svg')
ON CONFLICT (id) DO NOTHING;

volcano/functions/catalog/index.js
volcano/functions/catalog/package.json
volcano/functions/place-order/index.js
volcano/functions/place-order/package.json

const { Pool } = require('pg');

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 3 });

function reply(statusCode, body) {
  return { statusCode, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) };
}

exports.handler = async (event) => {
  if (event.method !== 'GET' && event.method !== 'HEAD') {
    return reply(405, { error: 'Use GET.' });
  }
  try {
    const { rows } = await pool.query(
      `SELECT id, name, description, price_cents, stock, image_path
         FROM public.products WHERE active ORDER BY created_at, id`,
    );
    return reply(200, { products: rows });
  } catch (error) {
    console.error('catalog failed', error);
    return reply(500, { error: 'Could not load the catalog.' });
  }
};

const { Pool } = require('pg');

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });

function reply(statusCode, body) {
  return {
    statusCode,
    headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },
    body: JSON.stringify(body),
  };
}

exports.handler = async (event) => {
  const auth = event.__volcano_auth;
  if (!auth || auth.role !== 'authenticated') {
    return reply(401, { error: 'Sign in to place an order.' });
  }

  const client = await pool.connect();
  let broken = false;
  try {
    await client.query('BEGIN');

    // Locking the cart makes a double-click wait for the first order, which
    // then empties the cart, so the second attempt finds nothing to buy.
    const { rows: cart } = await client.query(
      `SELECT product_id, quantity FROM public.cart_items
        WHERE user_id = $1 ORDER BY product_id FOR UPDATE`,
      [auth.user_id],
    );
    if (cart.length === 0) {
      await client.query('ROLLBACK');
      return reply(400, { error: 'Your cart is empty.' });
    }

    // Take the stock and read the price in one statement per product. Rows are
    // locked in product id order, so two orders can't deadlock, and a second
    // order for the last unit waits here, then matches no row.
    const items = [];
    for (const { product_id, quantity } of cart) {
      const { rows } = await client.query(
        `UPDATE public.products SET stock = stock - $2
          WHERE id = $1 AND active AND stock >= $2
          RETURNING id, name, price_cents`,
        [product_id, quantity],
      );
      if (rows.length === 0) {
        await client.query('ROLLBACK');
        const { rows: left } = await client.query(
          'SELECT name, stock FROM public.products WHERE id = $1 AND active',
          [product_id],
        );
        let message = 'An item in your cart is no longer sold. Remove it and try again.';
        if (left[0]?.stock === 0) message = `${left[0].name} just sold out. Remove it and try again.`;
        else if (left.length) message = `Only ${left[0].stock} × ${left[0].name} left. Update your cart and try again.`;
        return reply(409, { error: message, product_id, available: left[0]?.stock ?? 0 });
      }
      items.push({ ...rows[0], quantity });
    }

    const total = items.reduce((sum, item) => sum + item.price_cents * item.quantity, 0);

    // No payment is taken. A charge can't be rolled back with this
    // transaction, so a payment provider goes after COMMIT (see below).
    const { rows: [order] } = await client.query(
      `INSERT INTO public.orders (user_id, total_cents) VALUES ($1, $2)
       RETURNING id, total_cents, status, created_at`,
      [auth.user_id, total],
    );
    await client.query(
      `INSERT INTO public.order_items
         (order_id, user_id, product_id, product_name, unit_price_cents, quantity)
       SELECT $1, $2, i.id, i.name, i.price_cents, i.quantity
         FROM jsonb_to_recordset($3::jsonb) AS i(id text, name text, price_cents int, quantity int)`,
      [order.id, auth.user_id, JSON.stringify(items)],
    );
    // Remove only what was bought: a row another tab added after the cart was
    // read isn't locked or priced, so it stays for the next order.
    await client.query(
      'DELETE FROM public.cart_items WHERE user_id = $1 AND product_id = ANY($2::text[])',
      [auth.user_id, cart.map((line) => line.product_id)],
    );
    await client.query('COMMIT');

    return reply(201, {
      order: {
        ...order,
        items: items.map((item) => ({
          product_id: item.id,
          product_name: item.name,
          unit_price_cents: item.price_cents,
          quantity: item.quantity,
        })),
      },
    });
  } catch (error) {
    // A connection that can't roll back is dropped from the pool, not reused.
    await client.query('ROLLBACK').catch(() => { broken = true; });
    console.error('place-order failed', error);
    return reply(500, { error: 'Could not place the order.' });
  } finally {
    client.release(broken);
  }
};

import { VolcanoClient } from '@volcano.dev/sdk';

const volcano = new VolcanoClient({
  apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY,
});
volcano.database(process.env.NEXT_PUBLIC_VOLCANO_DATABASE);
const { user } = await volcano.initialize(); // null until someone signs in

async function loadCatalog() {
  const response = await fetch('/api/products', { cache: 'no-store' });
  const data = await response.json().catch(() => ({}));
  if (!response.ok) throw new Error(data.error || 'Could not load the catalog.');
  return data.products;
}

async function placeOrder() {
  const { data, status, error } = await volcano.functions.invoke('place-order');
  if (error) throw new Error(error.message || 'Could not place the order.');
  if (status >= 400) throw new Error(data?.error || 'Could not place the order.');
  return data.order;
}

async function setCartQuantity(productId, quantity) {
  if (quantity <= 0) {
    const { error } = await volcano.delete('cart_items').eq('product_id', productId);
    if (error) throw error;
    return;
  }
  const updated = await volcano.update('cart_items', { quantity }).eq('product_id', productId);
  if (updated.error) throw updated.error;
  if (updated.data.length > 0) return;
  const inserted = await volcano.insert('cart_items', { product_id: productId, quantity });
  if (!inserted.error) return;
  if (!/23505|duplicate key/.test(inserted.error.message)) throw inserted.error;
  const retried = await volcano.update('cart_items', { quantity }).eq('product_id', productId);
  if (retried.error) throw retried.error;
}

async function loadOrders() {
  const orders = await volcano.from('orders').select('id,total_cents,status,created_at')
    .order('created_at', { ascending: false }).limit(20);
  if (orders.error) throw orders.error;
  if (orders.data.length === 0) return [];
  const items = await volcano.from('order_items')
    .select('order_id,product_id,product_name,unit_price_cents,quantity')
    .in('order_id', orders.data.map((order) => order.id));
  if (items.error) throw items.error;
  return orders.data.map((order) => ({
    ...order,
    items: items.data.filter((item) => item.order_id === order.id),
  }));
}

version: 1
auth:
  signup:
    enable_signup: true
    enable_anonymous_signins: false
  cors:
    enabled: true
    allowed_origins:
      - http://localhost:3000
functions:
  - name: catalog
    visibility: public
    invocation_mode: http
    variable_scope: scoped
    variables:
      - DATABASE_URL
  - name: place-order
    visibility: authenticated
    variable_scope: scoped
    variables:
      - DATABASE_URL
frontends:
  - name: web
    variable_scope: scoped
    variables:
      - NEXT_PUBLIC_VOLCANO_API_URL
      - NEXT_PUBLIC_VOLCANO_ANON_KEY
      - NEXT_PUBLIC_VOLCANO_DATABASE
    function_routes:
      - function: catalog
        path_prefix: /api/products
        strip_prefix: true

NEXT_PUBLIC_VOLCANO_API_URL=https://api.volcano.dev
NEXT_PUBLIC_VOLCANO_ANON_KEY=ak-your-project-key
NEXT_PUBLIC_VOLCANO_DATABASE=shop
DATABASE_URL=postgresql://your-connection-string

volcano cloud deploy --env-file volcano/cloud.env --with-migrations -d shop

const nextConfig = {
  async rewrites() {
    if (!process.env.CATALOG_ORIGIN) return [];
    return [{ source: '/api/products', destination: `${process.env.CATALOG_ORIGIN}/api/products` }];
  },
};

export default nextConfig;

PASS a signed-out visitor can browse the catalog — 200, 8 products
PASS the anon key alone can't invoke functions — 403 anon key does not have functions.invoke permission
PASS a signed-out visitor can't place an order — 403 anon key does not have functions.invoke permission
PASS a signed-out visitor can't read orders — 401 {"error":"Invalid or expired token"}
PASS two distinct signed-in shoppers
PASS A places an order — 201 596cdb5d-ec24-4957-b4b7-f51f4ffbd146
PASS the forged price and total are ignored — total 2500, unit 1250
PASS the order took the stock — stock 3
PASS placing the order emptied A's cart
PASS a second click finds an empty cart — 400 Your cart is empty.
PASS A sees the order and its items
PASS B can't read A's order — 0 rows
PASS B can't read A's order items — 0 rows
PASS A can't insert an order directly — Query failed: ERROR: permission denied for table orders (SQLSTATE 42501)
PASS A can't change an order total — Query failed: ERROR: permission denied for table orders (SQLSTATE 42501)
PASS A can't change a price — Query failed: ERROR: permission denied for table products (SQLSTATE 42501)
PASS a cart row can't carry a price — Query failed: ERROR: column "price_cents" of relation "cart_items" does not exist (SQLSTATE 42703)
PASS A can't add to B's cart — Query failed: ERROR: permission denied for table cart_items (SQLSTATE 42501)
PASS two orders for the last unit: one succeeds, one is refused — 409 Smoke last unit just sold out. Remove it and try again.
PASS the last unit was sold once and stock is 0 — sold 1
PASS the database refuses negative stock — new row for relation "products" violates check constraint "products_stock_check"