stackport 0.1.0__tar.gz

stackport-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DaviReisVieira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stackport-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include ui/dist *

stackport-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: stackport
+Version: 0.1.0
+Summary: Universal AWS resource browser for local emulators
+Author: Davi Reis Vieira
+License: MIT
+Project-URL: Homepage, https://github.com/DaviReisVieira/stackport
+Project-URL: Repository, https://github.com/DaviReisVieira/stackport
+Project-URL: Issues, https://github.com/DaviReisVieira/stackport/issues
+Keywords: aws,localstack,s3,browser,devtools,emulator
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: boto3>=1.35.0
+Dynamic: license-file
+
+# StackPort
+
+[![CI](https://github.com/DaviReisVieira/stackport/actions/workflows/ci.yml/badge.svg)](https://github.com/DaviReisVieira/stackport/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stackport)](https://pypi.org/project/stackport/)
+[![Docker](https://img.shields.io/docker/pulls/davireis/stackport)](https://hub.docker.com/r/davireis/stackport)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Universal AWS resource browser for local emulators. Works with **LocalStack**, **MiniStack**, **Moto**, or any AWS-compatible endpoint.
+
+<!-- TODO: Add screenshot here -->
+<!-- ![StackPort Dashboard](docs/screenshot.png) -->
+
+## Features
+
+- Browse and inspect resources across **35 AWS services**
+- S3 file browser with folder navigation, search, pagination, and download
+- Dashboard with service health, resource counts, and auto-refresh
+- Single Docker image, zero AWS dependencies
+
+## Quick Start
+
+### pip
+
+```bash
+pip install stackport
+AWS_ENDPOINT_URL=http://localhost:4566 stackport
+# Open http://localhost:8080
+```
+
+### Docker
+
+```bash
+docker run -p 8080:8080 -e AWS_ENDPOINT_URL=http://host.docker.internal:4566 davireis/stackport
+```
+
+### Docker Compose
+
+```bash
+curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docker-compose.yml
+docker compose up -d
+# Open http://localhost:8080
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `AWS_ENDPOINT_URL` | `http://localhost:4566` | Target AWS endpoint |
+| `AWS_REGION` | `us-east-1` | AWS region |
+| `AWS_ACCESS_KEY_ID` | `test` | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | `test` | AWS secret key |
+| `STACKPORT_PORT` | `8080` | StackPort server port |
+| `STACKPORT_SERVICES` | *(35 services)* | Comma-separated services to probe |
+
+## Supported Services (35)
+
+ACM, API Gateway, AppSync, Athena, CloudFormation, CloudFront, Cognito (IDP + Identity), DynamoDB, EC2, ECR, ECS, ElastiCache, EFS, ELB, EMR, EventBridge, Firehose, Glue, IAM, Kinesis, KMS, Lambda, CloudWatch Logs, CloudWatch Monitoring, RDS, Route 53, S3, Secrets Manager, SES, SNS, SQS, SSM, Step Functions, WAFv2
+
+S3 has a dedicated file browser. All other services use the generic resource table with detail view.
+
+## Development
+
+```bash
+git clone https://github.com/DaviReisVieira/stackport.git
+cd stackport
+pip install -e .
+cd ui && npm install && npm run dev
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
+## License
+
+MIT

stackport-0.1.0/README.md

@@ -0,0 +1,74 @@
+# StackPort
+
+[![CI](https://github.com/DaviReisVieira/stackport/actions/workflows/ci.yml/badge.svg)](https://github.com/DaviReisVieira/stackport/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stackport)](https://pypi.org/project/stackport/)
+[![Docker](https://img.shields.io/docker/pulls/davireis/stackport)](https://hub.docker.com/r/davireis/stackport)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Universal AWS resource browser for local emulators. Works with **LocalStack**, **MiniStack**, **Moto**, or any AWS-compatible endpoint.
+
+<!-- TODO: Add screenshot here -->
+<!-- ![StackPort Dashboard](docs/screenshot.png) -->
+
+## Features
+
+- Browse and inspect resources across **35 AWS services**
+- S3 file browser with folder navigation, search, pagination, and download
+- Dashboard with service health, resource counts, and auto-refresh
+- Single Docker image, zero AWS dependencies
+
+## Quick Start
+
+### pip
+
+```bash
+pip install stackport
+AWS_ENDPOINT_URL=http://localhost:4566 stackport
+# Open http://localhost:8080
+```
+
+### Docker
+
+```bash
+docker run -p 8080:8080 -e AWS_ENDPOINT_URL=http://host.docker.internal:4566 davireis/stackport
+```
+
+### Docker Compose
+
+```bash
+curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docker-compose.yml
+docker compose up -d
+# Open http://localhost:8080
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `AWS_ENDPOINT_URL` | `http://localhost:4566` | Target AWS endpoint |
+| `AWS_REGION` | `us-east-1` | AWS region |
+| `AWS_ACCESS_KEY_ID` | `test` | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | `test` | AWS secret key |
+| `STACKPORT_PORT` | `8080` | StackPort server port |
+| `STACKPORT_SERVICES` | *(35 services)* | Comma-separated services to probe |
+
+## Supported Services (35)
+
+ACM, API Gateway, AppSync, Athena, CloudFormation, CloudFront, Cognito (IDP + Identity), DynamoDB, EC2, ECR, ECS, ElastiCache, EFS, ELB, EMR, EventBridge, Firehose, Glue, IAM, Kinesis, KMS, Lambda, CloudWatch Logs, CloudWatch Monitoring, RDS, Route 53, S3, Secrets Manager, SES, SNS, SQS, SSM, Step Functions, WAFv2
+
+S3 has a dedicated file browser. All other services use the generic resource table with detail view.
+
+## Development
+
+```bash
+git clone https://github.com/DaviReisVieira/stackport.git
+cd stackport
+pip install -e .
+cd ui && npm install && npm run dev
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
+## License
+
+MIT

stackport-0.1.0/backend/aws_client.py

@@ -0,0 +1,22 @@
+import functools
+
+import boto3
+
+from backend.config import (
+    AWS_ACCESS_KEY_ID,
+    AWS_ENDPOINT_URL,
+    AWS_REGION,
+    AWS_SECRET_ACCESS_KEY,
+)
+
+
+@functools.lru_cache(maxsize=64)
+def get_client(service_name: str):
+    """Return a boto3 client configured for the target AWS-compatible endpoint."""
+    return boto3.client(
+        service_name,
+        endpoint_url=AWS_ENDPOINT_URL,
+        region_name=AWS_REGION,
+        aws_access_key_id=AWS_ACCESS_KEY_ID,
+        aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
+    )

stackport-0.1.0/backend/cache.py

@@ -0,0 +1,24 @@
+import threading
+import time
+
+
+class TTLCache:
+    def __init__(self):
+        self._store: dict = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str):
+        with self._lock:
+            if key in self._store:
+                value, expiry = self._store[key]
+                if time.time() < expiry:
+                    return value
+                del self._store[key]
+        return None
+
+    def set(self, key: str, value, ttl: float = 5):
+        with self._lock:
+            self._store[key] = (value, time.time() + ttl)
+
+
+cache = TTLCache()

stackport-0.1.0/backend/config.py

@@ -0,0 +1,14 @@
+import os
+
+AWS_ENDPOINT_URL: str = os.environ.get("AWS_ENDPOINT_URL", "http://localhost:4566")
+AWS_REGION: str = os.environ.get("AWS_REGION", "us-east-1")
+AWS_ACCESS_KEY_ID: str = os.environ.get("AWS_ACCESS_KEY_ID", "test")
+AWS_SECRET_ACCESS_KEY: str = os.environ.get("AWS_SECRET_ACCESS_KEY", "test")
+STACKPORT_PORT: int = int(os.environ.get("STACKPORT_PORT", "8080"))
+STACKPORT_SERVICES: str = os.environ.get(
+    "STACKPORT_SERVICES",
+    "s3,sqs,sns,dynamodb,lambda,iam,logs,ssm,secretsmanager,kinesis,events,ec2,"
+    "route53,kms,cloudformation,stepfunctions,rds,ecs,monitoring,ses,acm,wafv2,"
+    "ecr,elasticache,glue,athena,apigateway,firehose,cognito-idp,cognito-identity,"
+    "elasticmapreduce,elasticloadbalancing,elasticfilesystem,cloudfront,appsync",
+)

stackport-0.1.0/backend/main.py

@@ -0,0 +1,53 @@
+import logging
+import os
+import time
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from backend.config import STACKPORT_PORT
+from backend.routes import resources, s3, stats
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="StackPort", docs_url="/api/docs")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(stats.router, prefix="/api")
+app.include_router(s3.router, prefix="/api/s3")
+app.include_router(resources.router, prefix="/api")
+
+# Serve UI static files — mount assets under /assets, SPA fallback for everything else
+ui_dist = os.path.join(os.path.dirname(__file__), "..", "ui", "dist")
+if os.path.isdir(ui_dist):
+    app.mount("/assets", StaticFiles(directory=os.path.join(ui_dist, "assets")), name="assets")
+
+    @app.get("/{path:path}")
+    def spa_fallback(path: str):
+        # Try to serve the file directly
+        file_path = os.path.join(ui_dist, path)
+        if path and os.path.isfile(file_path):
+            return FileResponse(file_path)
+        # SPA fallback: return index.html
+        return FileResponse(os.path.join(ui_dist, "index.html"))
+
+
+def cli():
+    uvicorn.run("backend.main:app", host="0.0.0.0", port=STACKPORT_PORT, reload=False)
+
+
+if __name__ == "__main__":
+    cli()

stackport-0.1.0/backend/routes/resources.py

@@ -0,0 +1,248 @@
+import logging
+
+from fastapi import APIRouter, HTTPException
+
+from backend.aws_client import get_client
+from backend.cache import cache
+from backend.routes.stats import SERVICE_REGISTRY, _METHOD_KWARGS, _count_items
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Maps (service, resource_type) -> (boto3_service, method, id_param, response_key)
+# response_key=None means return the full response (minus ResponseMetadata)
+DESCRIBE_REGISTRY: dict[tuple[str, str], tuple[str, str, str, str | None]] = {
+    # Storage
+    ("s3", "buckets"): ("s3", "list_objects_v2", "Bucket", "Contents"),
+    # Compute
+    ("lambda", "functions"): ("lambda", "get_function", "FunctionName", None),
+    ("ecs", "clusters"): ("ecs", "describe_clusters", "clusters", "clusters"),
+    ("ecs", "task_definitions"): ("ecs", "describe_task_definition", "taskDefinition", "taskDefinition"),
+    # Database
+    ("dynamodb", "tables"): ("dynamodb", "describe_table", "TableName", "Table"),
+    ("rds", "db_instances"): ("rds", "describe_db_instances", "DBInstanceIdentifier", "DBInstances"),
+    ("rds", "db_clusters"): ("rds", "describe_db_clusters", "DBClusterIdentifier", "DBClusters"),
+    ("elasticache", "cache_clusters"): ("elasticache", "describe_cache_clusters", "CacheClusterId", None),
+    # Messaging
+    ("sqs", "queues"): ("sqs", "get_queue_attributes", "QueueUrl", "Attributes"),
+    ("sns", "topics"): ("sns", "get_topic_attributes", "TopicArn", "Attributes"),
+    ("kinesis", "streams"): ("kinesis", "describe_stream", "StreamName", "StreamDescription"),
+    ("firehose", "delivery_streams"): ("firehose", "describe_delivery_stream", "DeliveryStreamName", "DeliveryStreamDescription"),
+    ("events", "rules"): ("events", "describe_rule", "Name", None),
+    ("events", "event_buses"): ("events", "describe_event_bus", "Name", None),
+    # Security & Identity
+    ("iam", "roles"): ("iam", "get_role", "RoleName", "Role"),
+    ("iam", "users"): ("iam", "get_user", "UserName", "User"),
+    ("iam", "policies"): ("iam", "get_policy", "PolicyArn", "Policy"),
+    ("secretsmanager", "secrets"): ("secretsmanager", "describe_secret", "SecretId", None),
+    ("kms", "keys"): ("kms", "describe_key", "KeyId", "KeyMetadata"),
+    ("acm", "certificates"): ("acm", "describe_certificate", "CertificateArn", "Certificate"),
+    ("cognito-idp", "user_pools"): ("cognito-idp", "describe_user_pool", "UserPoolId", "UserPool"),
+    ("cognito-identity", "identity_pools"): ("cognito-identity", "describe_identity_pool", "IdentityPoolId", None),
+    # Management
+    ("logs", "log_groups"): ("logs", "describe_log_groups", "logGroupNamePrefix", "logGroups"),
+    ("ssm", "parameters"): ("ssm", "get_parameter", "Name", "Parameter"),
+    ("cloudformation", "stacks"): ("cloudformation", "describe_stacks", "StackName", "Stacks"),
+    ("stepfunctions", "state_machines"): ("stepfunctions", "describe_state_machine", "stateMachineArn", None),
+    ("monitoring", "alarms"): ("cloudwatch", "describe_alarms", "AlarmNames", "MetricAlarms"),
+    ("monitoring", "dashboards"): ("cloudwatch", "get_dashboard", "DashboardName", None),
+    # Networking & CDN
+    ("route53", "hosted_zones"): ("route53", "get_hosted_zone", "Id", "HostedZone"),
+    ("cloudfront", "distributions"): ("cloudfront", "get_distribution", "Id", "Distribution"),
+    ("elasticloadbalancing", "load_balancers"): ("elbv2", "describe_load_balancers", "LoadBalancerArns", "LoadBalancers"),
+    # EC2
+    ("ec2", "instances"): ("ec2", "describe_instances", "InstanceIds", "Reservations"),
+    ("ec2", "vpcs"): ("ec2", "describe_vpcs", "VpcIds", "Vpcs"),
+    ("ec2", "subnets"): ("ec2", "describe_subnets", "SubnetIds", "Subnets"),
+    ("ec2", "security_groups"): ("ec2", "describe_security_groups", "GroupIds", "SecurityGroups"),
+    ("ec2", "volumes"): ("ec2", "describe_volumes", "VolumeIds", "Volumes"),
+    ("elasticfilesystem", "file_systems"): ("efs", "describe_file_systems", "FileSystemId", "FileSystems"),
+    # Containers
+    ("ecr", "repositories"): ("ecr", "describe_repositories", "repositoryNames", "repositories"),
+    # Analytics & ETL
+    ("glue", "databases"): ("glue", "get_database", "Name", "Database"),
+    ("glue", "crawlers"): ("glue", "get_crawler", "Name", "Crawler"),
+    ("athena", "workgroups"): ("athena", "get_work_group", "WorkGroup", "WorkGroup"),
+    # API
+    ("apigateway", "apis"): ("apigatewayv2", "get_api", "ApiId", None),
+    ("appsync", "graphql_apis"): ("appsync", "get_graphql_api", "apiId", "graphqlApi"),
+    # EMR
+    ("elasticmapreduce", "clusters"): ("emr", "describe_cluster", "ClusterId", "Cluster"),
+}
+
+# Known ID field names for extracting a resource identifier from list results
+_ID_FIELDS = [
+    "BucketName",
+    "FunctionName",
+    "TableName",
+    "TopicArn",
+    "QueueUrl",
+    "RoleName",
+    "UserName",
+    "PolicyName",
+    "Arn",
+    "PolicyArn",
+    "logGroupName",
+    "Name",
+    "SecretName",
+    "StreamName",
+    "RuleName",
+    "InstanceId",
+    "VpcId",
+    "SubnetId",
+    "GroupId",
+    "VolumeId",
+    "HostedZoneId",
+    "Id",
+    "KeyId",
+    "StackName",
+    "stateMachineArn",
+    "DBInstanceIdentifier",
+    "DBClusterIdentifier",
+    "clusterArn",
+    "CertificateArn",
+    "repositoryName",
+    "CacheClusterId",
+    "DeliveryStreamName",
+    "WorkGroupName",
+    "ApiId",
+    "UserPoolId",
+    "IdentityPoolId",
+    "LoadBalancerArn",
+    "FileSystemId",
+    "AlarmName",
+    "DashboardName",
+    "CrawlerName",
+    "DatabaseName",
+    "DistributionId",
+]
+
+
+def _extract_id(item) -> str:
+    """Extract a usable ID from a list API result item."""
+    if isinstance(item, str):
+        return item
+    if isinstance(item, dict):
+        for field in _ID_FIELDS:
+            if field in item:
+                return str(item[field])
+        # Fallback: first string value
+        for v in item.values():
+            if isinstance(v, str):
+                return v
+    return str(item)
+
+
+def _summarize_item(item) -> dict:
+    """Create a summary dict from a list API result item."""
+    if isinstance(item, str):
+        return {"id": item}
+    if isinstance(item, dict):
+        summary = {"id": _extract_id(item)}
+        for key, value in item.items():
+            if isinstance(value, (str, int, float, bool)) or value is None:
+                summary[key] = value
+            elif hasattr(value, "isoformat"):
+                summary[key] = value.isoformat()
+        return summary
+    return {"id": str(item)}
+
+
+@router.get("/resources/{service}")
+def list_resources(service: str):
+    cache_key = f"resources:{service}"
+    cached = cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    registry_entries = SERVICE_REGISTRY.get(service)
+    if not registry_entries:
+        raise HTTPException(status_code=404, detail=f"Unknown service: {service}")
+
+    resources: dict[str, list[dict]] = {}
+    for resource_type, boto3_service, method_name, response_key in registry_entries:
+        try:
+            client = get_client(boto3_service)
+            method = getattr(client, method_name)
+            kwargs = _METHOD_KWARGS.get((boto3_service, method_name), {})
+            resp = method(**kwargs)
+            items = resp.get(response_key, [])
+            # Handle nested structures (e.g., cloudfront DistributionList.Items)
+            if isinstance(items, dict) and "Items" in items:
+                items = items.get("Items", []) or []
+            resources[resource_type] = [_summarize_item(item) for item in items]
+        except Exception:
+            logger.debug("Failed to list %s/%s", service, resource_type, exc_info=True)
+            resources[resource_type] = []
+
+    result = {"service": service, "resources": resources}
+    cache.set(cache_key, result, ttl=5)
+    return result
+
+
+@router.get("/resources/{service}/{res_type}/{res_id:path}")
+def get_resource_detail(service: str, res_type: str, res_id: str):
+    cache_key = f"detail:{service}:{res_type}:{res_id}"
+    cached = cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    lookup = DESCRIBE_REGISTRY.get((service, res_type))
+    if not lookup:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No detail lookup registered for {service}/{res_type}",
+        )
+
+    boto3_service, method_name, id_param, response_key = lookup
+
+    # Some APIs take list parameters (e.g., InstanceIds, VpcIds)
+    _LIST_PARAMS = {
+        "InstanceIds", "VpcIds", "SubnetIds", "GroupIds", "VolumeIds",
+        "repositoryNames", "clusters", "AlarmNames", "LoadBalancerArns",
+    }
+
+    try:
+        client = get_client(boto3_service)
+        method = getattr(client, method_name)
+        if id_param in _LIST_PARAMS:
+            resp = method(**{id_param: [res_id]})
+        else:
+            resp = method(**{id_param: res_id})
+
+        # Remove boto3 metadata
+        resp.pop("ResponseMetadata", None)
+
+        if response_key is not None:
+            detail = resp.get(response_key, resp)
+        else:
+            detail = resp
+
+        # Convert datetime objects for JSON serialization
+        detail = _serialize(detail)
+
+        result = {
+            "service": service,
+            "type": res_type,
+            "id": res_id,
+            "detail": detail,
+        }
+        cache.set(cache_key, result, ttl=5)
+        return result
+    except Exception as exc:
+        logger.warning("Failed to get detail for %s/%s/%s", service, res_type, res_id, exc_info=True)
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+
+def _serialize(obj):
+    """Recursively convert non-JSON-serializable types."""
+    if isinstance(obj, dict):
+        return {k: _serialize(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_serialize(v) for v in obj]
+    if hasattr(obj, "isoformat"):
+        return obj.isoformat()
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="replace")
+    return obj