yao/sui/docs/page-config.md

Page Configuration

Each SUI page can have a configuration file (<page>.config) that defines page-level settings including title, guards, caching, and API options.

File Naming

Configuration files use the naming convention <page>.config:

/pages/users/
├── users.html
├── users.css
├── users.ts
├── users.json
├── users.config        # Page configuration
└── users.backend.ts

Configuration Structure

{
  "title": "Page Title",
  "description": "Page description",
  "guard": "oauth",
  "cache": 3600,
  "dataCache": 300,
  "cacheStore": "redis",
  "root": "/custom-root",
  "seo": {
    "title": "SEO Title",
    "description": "SEO Description",
    "keywords": "keyword1, keyword2",
    "image": "/images/og-image.png",
    "url": "https://example.com/page"
  },
  "api": {
    "prefix": "Api",
    "defaultGuard": "oauth",
    "guards": {
      "PublicMethod": "-",
      "AdminMethod": "bearer-jwt"
    }
  }
}

Configuration Options

Basic Options

Option	Type	Description	Default
title	string	Page title	-
description	string	Page description	-
guard	string	Guard for page rendering	-
cache	number	Page cache duration in seconds	0
dataCache	number	Data cache duration in seconds	0
cacheStore	string	Cache store name (e.g., "redis")	-
root	string	Custom root path for the page	-

SEO Options

{
  "seo": {
    "title": "SEO Title - Different from page title",
    "description": "Meta description for search engines",
    "keywords": "comma, separated, keywords",
    "image": "/images/og-image.png",
    "url": "https://example.com/canonical-url"
  }
}

API Options

The api section configures guards for backend API methods (called via $Backend().Call()):

{
  "api": {
    "prefix": "Api",
    "defaultGuard": "oauth",
    "guards": {
      "MethodName": "guard-name"
    }
  }
}

Option	Type	Description	Default
prefix	string	Method prefix for API functions	"Api"
defaultGuard	string	Default guard for all API methods	-
guards	object	Per-method guard overrides	-

Guards

SUI supports the following built-in guards:

Guard	Description
oauth	OAuth 2.1 authentication (recommended)
bearer-jwt	Bearer token JWT authentication
cookie-jwt	Cookie-based JWT authentication
query-jwt	Query string JWT authentication (?__tk=token)
cookie-trace	Session tracking via cookie
-	No authentication (public access)

Page Guard vs API Guard

• Page Guard (guard): Controls access to page rendering
• API Guard (api.defaultGuard / api.guards): Controls access to backend API methods

{
  "guard": "oauth",
  "api": {
    "defaultGuard": "oauth",
    "guards": {
      "PublicSearch": "-"
    }
  }
}

In this example:

• Page rendering requires OAuth authentication
• All API methods require OAuth by default
• ApiPublicSearch method is publicly accessible

Examples

Public Page

{
  "title": "Welcome",
  "description": "Public landing page"
}

Protected Page with OAuth

{
  "title": "Dashboard",
  "guard": "oauth",
  "api": {
    "defaultGuard": "oauth"
  }
}

Mixed Access Page

{
  "title": "Product Catalog",
  "guard": "-",
  "api": {
    "defaultGuard": "-",
    "guards": {
      "AddToCart": "oauth",
      "Checkout": "oauth"
    }
  }
}

Page is public, most API methods are public, but cart and checkout require authentication.

Cached Page

{
  "title": "Blog Post",
  "cache": 3600,
  "dataCache": 300,
  "guard": "-"
}

Full Configuration Example

{
  "title": "User Settings",
  "description": "Manage your account settings",
  "guard": "oauth",
  "cache": 0,
  "dataCache": 60,
  "seo": {
    "title": "Account Settings | MyApp",
    "description": "Configure your account preferences and security settings"
  },
  "api": {
    "defaultGuard": "oauth",
    "guards": {
      "GetPublicProfile": "-",
      "UpdateProfile": "oauth",
      "DeleteAccount": "oauth"
    }
  }
}

Accessing Authorized Info

When using oauth guard, the authorized user information is available in:

Backend Scripts

function ApiGetUserData(request: Request): any {
  // Access OAuth info from request.authorized
  const userId = request.authorized?.user_id;
  const teamId = request.authorized?.team_id;
  const clientId = request.authorized?.client_id;
  const scope = request.authorized?.scope;

  // Access data constraints (set by ACL)
  const ownerOnly = request.authorized?.constraints?.owner_only;
  const teamOnly = request.authorized?.constraints?.team_only;

  return Process("models.user.Find", userId);
}

Data Binding (.json)

{
  "userId": "$auth.user_id",
  "teamId": "$auth.team_id"
}

HTML Templates

<p>Welcome, User {{ $auth.user_id }}</p>
<p s:if="$auth.team_id">Team: {{ $auth.team_id }}</p>

Custom Guards

You can use custom process-based guards:

{
  "guard": "scripts.guards.CheckAdmin",
  "api": {
    "defaultGuard": "scripts.guards.CheckPermission"
  }
}

The guard process receives the request context and should throw an exception to deny access.