Stelvio Framework

All infrastructure definitions (like DynamoDB tables and REST APIs) must be placed inside the function decorated with @app.run.

When you run stlv diff or stlv deploy, Stelvio generates a stlv_resources.py file. This file contains a Resources class that provides type-safe access to your infrastructure's metadata (like table names or ARNs) within your Lambda function code.

from stelvio.app import StelvioApp
from stelvio.aws.dynamo_db import DynamoTable, FieldType
from stelvio.aws.api_gateway import RestApi

app = StelvioApp("stelvio-app")

@app.run
def run() -> None:
    # Define a DynamoDB table
    table = DynamoTable(
        name="todos",
        fields={
            "username": FieldType.STRING,
            "created": FieldType.STRING,
        },
        partition_key="username",
        sort_key='created'
    )
    
    # Define a REST API and its routes
    api = RestApi("todo-api")
    # The 'links' argument automates IAM permissions and env vars for the handler
    api.route("POST", "/todos", handler="functions/todos.post", links=[table])
    api.route("GET", "/todos/{username}", handler="functions/todos.get")

The CloudFront Router is a component used to expose multiple Stelvio components (like S3 Buckets or APIs) under a single domain. It acts as a gateway that maps incoming request paths to specific origins.

Key behaviors:

• Path Stripping: When a route is defined (e.g., router.route("/api", api)), the router strips the prefix before forwarding the request. A request to /api/users reaches the API at /users.
• Automatic Path Specificity: Stelvio automatically sorts routes by specificity. Longer, more specific paths take precedence over shorter ones, regardless of the order they are defined in your code.
• Catch-all: The root path / acts as a catch-all. If no root path is defined, unmatched requests return a 404.
• Origin Uniqueness: Each component or external URL can only be routed to a single path. You cannot point multiple routes to the same origin.

@app.run
def run() -> None:
    domain_name = "example.com"

    bucket = Bucket("static-files-bucket")
    api = RestApi("my-api")
    api.route("GET", "/", "functions/hello.handler")

    # Creating the CloudFront Router
    router = Router("rtr-test", custom_domain=domain_name)
    
    # Mapping paths to components
    router.route("/files", bucket)
    router.route("/api", api)

When the same tag key is defined at multiple levels, Stelvio follows a specific order of precedence. Higher-specificity layers override lower-priority ones:

1. customize overrides (highest priority)
2. Component tags (tags=... on a component)
3. Global tags (StelvioAppConfig.tags)
4. Auto-tags (stelvio:app, stelvio:env) (lowest priority)

Example of precedence behavior: If a Global tag sets Shared=global and a Component tag sets Shared=component, the resulting resource will have Shared=component.

from stelvio.aws.queue import Queue
from stelvio.config import StelvioAppConfig

@app.config
def config(env: str) -> StelvioAppConfig:
    # Sets 'Shared=global'
    return StelvioAppConfig(tags={"Shared": "global", "GlobalOnly": "yes"})

@app.run
def run() -> None:
    # Sets 'Shared=component' (overriding global) and 'ComponentOnly=yes'
    Queue("jobs", tags={"Shared": "component", "ComponentOnly": "yes"})

Stelvio uses a layered tagging system to attach key-value pairs to AWS resources. This allows for cost tracking, resource identification, and policy enforcement in the AWS console and Cost Explorer.

There are three primary layers of tags:

1. Auto-tags: Automatically applied to every resource by Stelvio.
2. Global tags: Defined in StelvioAppConfig and applied to all components in the application.
3. Component tags: Defined on a per-component basis for fine-grained control.

Tags are applied via the AWS provider's default_tags mechanism where possible, ensuring broad coverage across taggable resources.

from stelvio.app import StelvioApp
from stelvio.config import StelvioAppConfig
from stelvio.aws.queue import Queue

app = StelvioApp("my-app")

# 1. Global Tags
@app.config
def config(env: str) -> StelvioAppConfig:
    return StelvioAppConfig(
        tags={
            "Team": "platform",
            "CostCenter": "infra",
        }
    )

# 2. Component Tags
orders = Queue(
    "orders",
    tags={
        "Service": "checkout",
        "Owner": "payments-team",
    },
)