KT Doc-Hub

Appearance

AWS stack mapserver-wfs ​

Overview ​

The mapserver-wfs stack in @tools/aws-deployer serves as a serverless Web Feature Service (WFS) proxy that dynamically generates MapServer configuration files and processes geospatial data requests. It acts as an intermediary between client applications and MapServer, providing secure, workspace-aware access to geospatial data.

Architecture ​

High-Level Flow ​

  1. Authentication & Validation - Validates JWT tokens containing workspace configuration
  2. Mapfile Generation - Dynamically builds MapServer configuration based on workspace settings using the @kt-domain/wfs-mapfile-generator package
  3. MapServer Execution - Spawns MapServer process to handle the WFS request
  4. Result Streaming - Streams MapServer output to S3 and returns redirect URL

Key Components ​

generateWfsResponse.ts (main handler)
├── buildWfsMapfile.ts (dynamic mapfile generation) which uses the `@kt-domain/wfs-mapfile-generator` package
├── spawnMapServerProcess.ts (MapServer process management)
├── streamToS3AndGetUrl.ts (S3 upload handling)
├── handleTypenameAlias.ts (typename processing)
├── getProxySecret.ts (JWT secret retrieval)
└── types.ts (TypeScript definitions)

Core Functionality ​

1. Request Authentication (generateWfsResponse.ts) ​

The function validates incoming requests using JWT tokens passed via the X-kt-ws-options header:

WfsConfig Config Documentation Here

typescript
type WSOptionsDecodedJWT = {
    wfsConfig: WfsConfig;
    mapConfig: {
        basePoint: Array<number>;
        center: Array<number>;
        bounds: Array<number>;
        useSuppliedCenter: boolean;
    };
    workspaceUser: string;
    exp: number;
};
  • JWT contains workspace-specific configuration including asset types, map bounds, and user context
  • Uses getProxySecret() to retrieve signing key for token verification
  • Returns 400 error for missing or invalid tokens

2. Dynamic Mapfile Generation (buildWfsMapfile.ts) ​

The system dynamically generates MapServer configuration files:

  • Database Credentials: Fetches read-only database credentials using @kt-core/db
  • Caching: Credentials are cached across Lambda invocations for performance
  • Configuration: Uses @kt-domain/wfs-mapfile-generator to build mapfile content
  • Workspace Awareness: Incorporates user workspace settings and asset type filters

3. MapServer Process Management (spawnMapServerProcess.ts) ​

Spawns and manages MapServer child processes:

  • Executes MapServer with the generated mapfile
  • Processes WFS query parameters (service, version, request, typename)
  • Handles typename aliases for backward compatibility
  • Captures stderr for error reporting

4. Result Handling ​

S3 Streaming (streamToS3AndGetUrl.ts):

  • Streams MapServer stdout directly to S3 bucket
  • Generates unique keys using timestamp: wfs-output/${Date.now()}.xml
  • Sets appropriate content-type headers (text/xml)
  • Returns presigned URL for client access

Response Types:

  • 302 Redirect: Standard success response with S3 URL location
  • 200 Debug: Returns MapServer logs when debug=true (non-production only)
  • 200 Config: Returns generated mapfile when showConfig=true (non-production only)
  • Error Responses: 400/422/500 for validation/processing errors

Environment Configuration ​

Required Environment Variables ​

  • OUTPUT_BUCKET_NAME: S3 bucket for storing WFS response files
  • AWS_REGION: AWS region for S3 client configuration
  • DEPLOY_MODE: Deployment mode (controls debug feature availability)

File Paths ​

  • /tmp/wfs.map: Temporary mapfile location for MapServer execution
  • /tmp/mapserver.log: MapServer debug log file (debug mode only)

Security Features ​

Authentication ​

  • JWT-based request authentication with workspace-scoped permissions
  • Proxy secret management for token verification
  • User context preservation throughout request lifecycle

Input Validation ​

  • SERVICE parameter validation (must be "WFS")
  • Required header validation (X-kt-ws-options, X-forwarded-host)
  • Query parameter sanitization through WfsRequestParams type

Environment Protection ​

  • Debug features disabled in production (DEPLOY_MODE !== "production")
  • Error message sanitization to prevent information disclosure
  • Secure credential handling with caching

Debug and Development Features ​

Debug Mode (?debug=true) ​

  • Enables MapServer debug logging
  • Returns debug log content instead of redirect
  • Only available in non-production environments

Configuration Inspection (?showConfig=true) ​

  • Returns generated mapfile content for inspection
  • Useful for troubleshooting mapfile generation issues
  • Only available in non-production environments

Error Handling ​

Common Error Scenarios ​

  1. Missing Authentication (400): X-kt-ws-options header missing
  2. Invalid JWT (400): Token verification failure
  3. Missing Host (400): X-forwarded-host header missing
  4. Invalid Service (422): SERVICE parameter not "WFS"
  5. Upload Failure (500): S3 upload error or MapServer process failure

Error Response Format ​

All errors return appropriate HTTP status codes with descriptive error messages:

  • Client errors (4xx): Input validation failures
  • Server errors (5xx): Processing or infrastructure failures

Performance Considerations ​

Optimization Strategies ​

  1. Credential Caching: Database credentials cached across Lambda invocations
  2. Streaming: Direct stream processing from MapServer to S3 (no intermediate buffering)
  3. Temporary Files: Uses Lambda's /tmp storage for mapfile generation
  4. Process Management: Efficient child process spawning and cleanup

Scaling Characteristics ​

  • Stateless: Each invocation is independent
  • Concurrent: Multiple requests processed in parallel
  • Resource Bounded: Limited by Lambda memory/CPU allocation
  • Storage: Uses S3 for result persistence (no local storage dependency)

Integration Points ​

Upstream Dependencies ​

  • @kt-core/db: Database credential management
  • @kt-domain/wfs-mapfile-generator: Mapfile generation logic
  • AWS S3: Result storage and delivery
  • AWS Secrets Manager: JWT signing key storage

Downstream Consumers ​

  • Client applications expecting WFS-compliant XML responses
  • Frontend mapping components requiring geospatial data
  • Mobile applications with offline mapping capabilities

Monitoring and Observability ​

Logging ​

  • Error logging for upload failures and processing errors
  • Debug logging available in development environments
  • MapServer stderr capture for diagnostic purposes

Metrics ​

  • HTTP status codes for success/failure tracking
  • Processing time through Lambda duration metrics
  • S3 upload success/failure rates