gh-rknall-claude-skills-newt-blueprint-generator/validation-reference.md

Validation Reference

This document provides a comprehensive reference for all validation rules and constraints in Pangolin Newt blueprints.

Table of Contents

1. Resource-Level Validations
2. Property Constraints
3. Common Validation Errors
4. Validation Quick Reference

Resource-Level Validations

Targets-Only Resources

A resource can contain only the targets field:

proxy-resources:
  additional-targets:
    targets:
      - site: another-site
        hostname: backend-server
        method: https
        port: 8443

When using targets-only:

• name field is NOT required
• protocol field is NOT required
• All other resource-level validations are skipped

Protocol-Specific Requirements

HTTP Protocol

Required fields:

• full-domain - Must be unique across all proxy resources
• All targets must have method field (http, https, or h2c)

Optional features:

• auth configuration (SSO, basic auth, pincode, password)
• headers array
• rules array
• host-header
• tls-server-name
• ssl boolean

Not allowed:

• proxy-port (use full-domain instead)

TCP/UDP Protocol

Required fields:

• proxy-port - Must be unique within proxy-resources
• Port range: 1-65535

Not allowed:

• method field in targets
• auth configuration (authentication not supported)
• full-domain (use proxy-port instead)

Property Constraints

Port Constraints

Property	Scope	Range	Uniqueness
proxy-port	proxy-resources	1-65535	Must be unique within proxy-resources
proxy-port	client-resources	1-65535	Must be unique within client-resources
port (target)	All	1-65535	No uniqueness constraint
internal-port	All	1-65535	No uniqueness constraint

Important: Cross-validation between proxy and client resources is NOT enforced. You can use the same port in both proxy-resources and client-resources.

Domain Constraints

Property	Scope	Uniqueness	Format
full-domain	proxy-resources (HTTP only)	Must be unique across all proxy resources	Valid domain name

String Length Constraints

Property	Min Length	Max Length	Context
name	2	100	All resources
hostname	1	255	All targets
site	2	100	Optional site identifier
header.name	1	-	Header names
header.value	1	-	Header values

Authentication Constraints

SSO Roles

• Cannot include "Admin" role (reserved)
• Must be array of strings
• Each role must be valid

SSO Users & Whitelist Users

• Must be valid email addresses
• Must be array of strings

Pincode

• Must be exactly 6 digits
• Type: number
• Example: 123456

Basic Auth

• Must have both user and password fields
• Both fields are required strings

Common Validation Errors

1. "Admin role cannot be included in sso-roles"

Cause: The Admin role is reserved and cannot be included in sso-roles array.

Solution:

# ❌ Wrong
auth:
  sso-enabled: true
  sso-roles:
    - Admin    # This will fail
    - Member

# ✅ Correct
auth:
  sso-enabled: true
  sso-roles:
    - Member
    - Developer

2. "Duplicate 'full-domain' values found"

Cause: Each full-domain must be unique across all proxy resources.

Solution:

# ❌ Wrong - same domain twice
proxy-resources:
  app1:
    full-domain: app.example.com
    # ...
  app2:
    full-domain: app.example.com  # Duplicate!
    # ...

# ✅ Correct - use different subdomains or paths
proxy-resources:
  app1:
    full-domain: app1.example.com
    # ...
  app2:
    full-domain: app2.example.com
    # ...

3. "Duplicate 'proxy-port' values found"

Cause: Port numbers in proxy-port must be unique within their resource type.

Solution:

# ❌ Wrong - same port twice in proxy-resources
proxy-resources:
  db1:
    protocol: tcp
    proxy-port: 5432
    # ...
  db2:
    protocol: tcp
    proxy-port: 5432  # Duplicate!
    # ...

# ✅ Correct - use different ports
proxy-resources:
  db1:
    protocol: tcp
    proxy-port: 5432
    # ...
  db2:
    protocol: tcp
    proxy-port: 5433
    # ...

4. "When protocol is 'http', all targets must have a 'method' field"

Cause: HTTP targets must specify connection method.

Solution:

# ❌ Wrong - missing method
proxy-resources:
  web-app:
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        # Missing method!

# ✅ Correct - method specified
proxy-resources:
  web-app:
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: https  # Added method

5. "When protocol is 'tcp' or 'udp', targets must not have a 'method' field"

Cause: TCP/UDP targets should not include the method field.

Solution:

# ❌ Wrong - method on TCP target
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432
        method: tcp  # Not allowed for TCP/UDP!

# ✅ Correct - no method field
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    targets:
      - hostname: localhost
        port: 5432
        # No method field

6. "When protocol is 'tcp' or 'udp', 'auth' must not be provided"

Cause: Authentication is only supported for HTTP resources.

Solution:

# ❌ Wrong - auth on TCP resource
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    auth:
      password: secret  # Not allowed!
    targets:
      - hostname: localhost
        port: 5432

# ✅ Correct - no auth on TCP
proxy-resources:
  database:
    protocol: tcp
    proxy-port: 5432
    # No auth field
    targets:
      - hostname: localhost
        port: 5432

7. "Resource must either be targets-only or have both 'name' and 'protocol' fields"

Cause: Incomplete resource definition.

Solution:

# ❌ Wrong - has name but no protocol
proxy-resources:
  incomplete:
    name: My Resource
    # Missing protocol!
    targets:
      - hostname: localhost
        port: 8080

# ✅ Correct - complete definition
proxy-resources:
  complete:
    name: My Resource
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        method: http

# ✅ Also correct - targets-only
proxy-resources:
  targets-only:
    targets:
      - hostname: localhost
        port: 8080
        method: http

Validation Quick Reference

✅ Valid Configurations

HTTP Resource - Complete

proxy-resources:
  web-app:
    name: Web Application
    protocol: http
    full-domain: app.example.com
    enabled: true
    ssl: true
    host-header: backend.internal
    tls-server-name: backend.internal
    headers:
      - name: X-Custom-Header
        value: custom-value
    auth:
      sso-enabled: true
      sso-roles:
        - Member
      sso-users:
        - user@example.com
    rules:
      - action: allow
        match: ip
        value: 1.1.1.1
    targets:
      - site: site-01
        hostname: localhost
        port: 8080
        method: https
        enabled: true
        path: /api
        path-match: prefix

TCP Resource - Complete

proxy-resources:
  database:
    name: PostgreSQL Database
    protocol: tcp
    proxy-port: 5432
    enabled: true
    targets:
      - site: site-01
        hostname: localhost
        port: 5432
        enabled: true

Targets-Only Resource

proxy-resources:
  additional-targets:
    targets:
      - site: site-02
        hostname: backend-02
        port: 8080
        method: http

Client Resource

client-resources:
  ssh-server:
    name: SSH Server
    protocol: tcp
    proxy-port: 2222
    hostname: localhost
    internal-port: 22
    site: site-01
    enabled: true

❌ Invalid Configurations

Mixed Protocol Requirements

# ❌ INVALID - HTTP resource with proxy-port instead of full-domain
proxy-resources:
  wrong:
    name: Wrong Config
    protocol: http
    proxy-port: 8080  # Should be full-domain for HTTP!
    targets:
      - hostname: localhost
        port: 8080
        method: http

TCP with Auth

# ❌ INVALID - TCP resource with auth
proxy-resources:
  wrong:
    name: Wrong Config
    protocol: tcp
    proxy-port: 5432
    auth:  # Auth not allowed on TCP/UDP!
      password: secret
    targets:
      - hostname: localhost
        port: 5432

Missing Required Fields

# ❌ INVALID - HTTP target without method
proxy-resources:
  wrong:
    name: Wrong Config
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: localhost
        port: 8080
        # Missing method field!

Validation Checklist

Before deploying a blueprint, verify:

• All HTTP resources have unique full-domain values
• All TCP/UDP resources have unique proxy-port values within their type
• All HTTP targets have method field specified
• No TCP/UDP targets have method field
• No TCP/UDP resources have auth configuration
• All port numbers are in range 1-65535
• All email addresses in sso-users and whitelist-users are valid
• SSO roles do not include "Admin"
• Pincode (if used) is exactly 6 digits
• Basic auth (if used) has both user and password fields
• String fields meet minimum/maximum length requirements
• Resources are either targets-only OR have both name and protocol