Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

docs: updating readme with supported services and new banner

Hector Ventura293aeeb6c6e8
diff --git a/README.md b/README.md
index a33333420e..19d7aeb513 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
<p align="center">
- <img src="logo.svg" alt="Floci" width="400" />
+ <img src="floci_banner.svg" alt="Floci"/>
</p>
<p align="center">
@@ -14,8 +14,6 @@
</p>
-<h3 align="center">🍿☁️ Light, fluffy, and always free</h3>
-
<p align="center">
<em>Named after <a href="https://en.wikipedia.org/wiki/Cirrocumulus_floccus">floccus</a> — the cloud formation that looks exactly like popcorn.</em>
</p>
@@ -54,7 +52,70 @@
| KMS (sign, verify, re-encrypt) | ✅ | ⚠️ Partial |
| Native binary | ✅ ~40 MB | ❌ |
-**21+ services. 408/408 SDK tests passing. Free forever.**
+**24 services. 408/408 SDK tests passing. Free forever.**
+
+## Architecture Overview
+
+```mermaid
+flowchart LR
+ Client["☁️ AWS SDK / CLI"]
+
+ subgraph Floci ["Floci — port 4566"]
+ Router["HTTP Router\n(JAX-RS / Vert.x)"]
+
+ subgraph Stateless ["Stateless Services"]
+ A["SSM · SQS · SNS\nIAM · STS · KMS\nSecrets Manager · SES\nCognito · Kinesis\nEventBridge · CloudWatch\nStep Functions · CloudFormation\nACM · API Gateway"]
+ end
+
+ subgraph Stateful ["Stateful Services"]
+ B["S3 · DynamoDB\nDynamoDB Streams"]
+ end
+
+ subgraph Containers ["Container Services 🐳"]
+ C["Lambda\nElastiCache\nRDS"]
+ end
+
+ Router --> Stateless
+ Router --> Stateful
+ Router --> Containers
+ Stateless & Stateful --> Store[("StorageBackend\nmemory · hybrid\npersistent · wal")]
+ end
+
+ Docker["🐳 Docker Engine"]
+ Client -->|"HTTP :4566\nAWS wire protocol"| Router
+ Containers -->|"Docker API\n+ IAM / SigV4 auth"| Docker
+```
+
+## Supported Services
+
+| Service | Ops | How it works | Notable features |
+|---|---|---|---|
+| **SSM Parameter Store** | 12 | In-process | Version history, labels, SecureString, tagging |
+| **SQS** | 17 | In-process | Standard & FIFO, DLQ, visibility timeout, batch, tagging |
+| **SNS** | 13 | In-process | Topics, subscriptions, SQS / Lambda / HTTP delivery, tagging |
+| **S3** | 30 | In-process | Versioning, multipart upload, pre-signed URLs, Object Lock, event notifications |
+| **DynamoDB** | 22 | In-process | GSI / LSI, Query, Scan, TTL, transactions, batch operations |
+| **DynamoDB Streams** | 5 | In-process | Shard iterators, records, Lambda ESM trigger |
+| **Lambda** | 25 | **Real Docker containers** | Warm pool, aliases, Function URLs, SQS / Kinesis / DDB Streams ESM |
+| **API Gateway REST** | 24 | In-process | Resources, methods, stages, Lambda proxy, MOCK integrations, AWS integrations |
+| **API Gateway v2 (HTTP)** | 16 | In-process | Routes, integrations, JWT authorizers, stages |
+| **IAM** | 65+ | In-process | Users, roles, groups, policies, instance profiles, access keys |
+| **STS** | 7 | In-process | AssumeRole, WebIdentity, SAML, GetFederationToken, GetSessionToken |
+| **Cognito** | 20 | In-process | User pools, app clients, auth flows, JWKS / OpenID well-known endpoints |
+| **KMS** | 15 | In-process | Encrypt / decrypt, sign / verify, data keys, aliases |
+| **Kinesis** | 15 | In-process | Streams, shards, enhanced fan-out, split / merge |
+| **Secrets Manager** | 10 | In-process | Versioning, resource policies, tagging |
+| **Step Functions** | 11 | In-process | ASL execution, task tokens, execution history |
+| **CloudFormation** | 12 | In-process | Stacks, change sets, resource provisioning |
+| **EventBridge** | 14 | In-process | Custom buses, rules, targets (SQS / SNS / Lambda) |
+| **CloudWatch Logs** | 14 | In-process | Log groups, streams, ingestion, filtering |
+| **CloudWatch Metrics** | 5 | In-process | Custom metrics, statistics, alarms |
+| **ElastiCache** | 9 | **Real Docker containers** | Redis / Valkey, IAM auth, SigV4 validation |
+| **RDS** | 14 | **Real Docker containers** | PostgreSQL & MySQL, IAM auth, JDBC-compatible |
+| **ACM** | 8 | In-process | Certificate issuance, validation lifecycle |
+| **SES** | 14 | In-process | Send email / raw email, identity verification, DKIM attributes |
+
+> **Lambda, ElastiCache, and RDS** spin up real Docker containers and support IAM authentication and SigV4 request signing — the same auth flow as production AWS.
## Quick Start
@@ -161,7 +222,7 @@ All settings are overridable via environment variables (`FLOCI_` prefix).
| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Default AWS account ID |
| `FLOCI_BASE_URL` | `http://localhost:4566` | Base URL used in API responses (e.g. SQS QueueUrl) |
| `FLOCI_HOSTNAME` | *(unset)* | Override hostname in response URLs (for Docker Compose) |
-| `FLOCI_STORAGE_MODE` | `hybrid` | `memory` · `persistent` · `hybrid` · `wal` |
+| `FLOCI_STORAGE_MODE` | `memory` | `memory` · `persistent` · `hybrid` · `wal` |
| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Data directory |
→ Full reference: [configuration docs](https://hectorvent.dev/floci/configuration/application-yml/)
diff --git a/floci_banner.svg b/floci_banner.svg
new file mode 100644
index 0000000000..0c19297f95
--- /dev/null
+++ b/floci_banner.svg
@@ -0,0 +1,126 @@
+<svg width="1280" height="640" viewBox="0 0 1280 640" xmlns="http://www.w3.org/2000/svg">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="0.6" y2="1">
+ <stop offset="0%" stop-color="#0d0f1a"/>
+ <stop offset="100%" stop-color="#12152b"/>
+ </linearGradient>
+ <radialGradient id="glow-amber" cx="50%" cy="34%" r="38%">
+ <stop offset="0%" stop-color="#f9a825" stop-opacity="0.22"/>
+ <stop offset="100%" stop-color="#f9a825" stop-opacity="0"/>
+ </radialGradient>
+ <radialGradient id="glow-indigo" cx="50%" cy="80%" r="50%">
+ <stop offset="0%" stop-color="#3949ab" stop-opacity="0.2"/>
+ <stop offset="100%" stop-color="#3949ab" stop-opacity="0"/>
+ </radialGradient>
+ <linearGradient id="pm" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#fff8e1"/>
+ <stop offset="100%" stop-color="#ffe082"/>
+ </linearGradient>
+ <linearGradient id="ps" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#ffe082"/>
+ <stop offset="100%" stop-color="#e6ac00"/>
+ </linearGradient>
+ <linearGradient id="wm" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#fff8e1"/>
+ <stop offset="55%" stop-color="#ffe082"/>
+ <stop offset="100%" stop-color="#e6ac00"/>
+ </linearGradient>
+ <pattern id="grid" width="56" height="56" patternUnits="userSpaceOnUse">
+ <path d="M 56 0 L 0 0 0 56" fill="none" stroke="#3949ab" stroke-width="0.5" opacity="0.15"/>
+ </pattern>
+ <radialGradient id="gmask-g" cx="50%" cy="40%" r="65%">
+ <stop offset="0%" stop-color="white" stop-opacity="0.9"/>
+ <stop offset="100%" stop-color="white" stop-opacity="0"/>
+ </radialGradient>
+ <mask id="gmask">
+ <rect width="1280" height="640" fill="url(#gmask-g)"/>
+ </mask>
+ </defs>
+
+ <!-- Background -->
+ <rect width="1280" height="640" fill="url(#bg)"/>
+ <rect width="1280" height="640" fill="url(#grid)" mask="url(#gmask)"/>
+ <rect width="1280" height="640" fill="url(#glow-amber)"/>
+ <rect width="1280" height="640" fill="url(#glow-indigo)"/>
+
+ <!-- Decorative rings -->
+ <circle cx="640" cy="225" r="290" fill="none" stroke="#3949ab" stroke-width="1" opacity="0.12"/>
+ <circle cx="640" cy="225" r="360" fill="none" stroke="#3949ab" stroke-width="1" opacity="0.07"/>
+
+ <!-- Cloud centered at (640, 215) -->
+ <g transform="translate(640,215) scale(1.9)">
+ <rect x="-108" y="-20" width="216" height="60" rx="30" fill="url(#ps)"/>
+ <circle cx="-74" cy="-20" r="40" fill="url(#ps)"/>
+ <circle cx="-22" cy="-44" r="52" fill="url(#pm)"/>
+ <circle cx="36" cy="-36" r="46" fill="url(#pm)"/>
+ <circle cx="86" cy="-18" r="34" fill="url(#ps)"/>
+ <ellipse cx="8" cy="-30" rx="72" ry="28" fill="#fff8e1" opacity="0.55"/>
+ <circle cx="-58" cy="-34" r="7" fill="#fff8e1" opacity="0.75"/>
+ <circle cx="-12" cy="-60" r="8.5" fill="#fff8e1" opacity="0.70"/>
+ <circle cx="38" cy="-54" r="7.5" fill="#fff8e1" opacity="0.70"/>
+ <circle cx="82" cy="-28" r="6" fill="#fff8e1" opacity="0.65"/>
+ <ellipse cx="4" cy="42" rx="90" ry="9" fill="#000" opacity="0.12"/>
+ </g>
+
+ <!-- Wordmark -->
+ <text x="640" y="402"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="118" font-weight="800" fill="url(#wm)"
+ text-anchor="middle" letter-spacing="-3">floci</text>
+
+ <!-- Tagline -->
+ <text x="640" y="446"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="21" font-weight="300" font-style="italic"
+ fill="#7986cb" text-anchor="middle" letter-spacing="0.5">Light, fluffy, and always free — AWS Local Emulator</text>
+
+ <!-- Stats row -->
+ <line x1="120" y1="490" x2="1160" y2="490" stroke="#3949ab" stroke-width="1" opacity="0.3"/>
+
+ <!-- 4 stats centered within lines x=120–1160, col=260px, centers=250,510,770,1030 -->
+
+ <!-- Stat 1: Startup -->
+ <text x="250" y="548"
+ font-family="'Courier New', Courier, monospace"
+ font-size="42" font-weight="700" fill="#ffe082" text-anchor="middle">24ms</text>
+ <text x="250" y="574"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="14" fill="#5c6bc0" text-anchor="middle" letter-spacing="0.3">Startup time</text>
+
+ <line x1="380" y1="510" x2="380" y2="580" stroke="#3949ab" stroke-width="1" opacity="0.4"/>
+
+ <!-- Stat 2: Memory -->
+ <text x="510" y="548"
+ font-family="'Courier New', Courier, monospace"
+ font-size="42" font-weight="700" fill="#ffe082" text-anchor="middle">13 MiB</text>
+ <text x="510" y="574"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="14" fill="#5c6bc0" text-anchor="middle" letter-spacing="0.3">Idle memory</text>
+
+ <line x1="640" y1="510" x2="640" y2="580" stroke="#3949ab" stroke-width="1" opacity="0.4"/>
+
+ <!-- Stat 3: Services -->
+ <text x="770" y="548"
+ font-family="'Courier New', Courier, monospace"
+ font-size="42" font-weight="700" fill="#ffe082" text-anchor="middle">~24</text>
+ <text x="770" y="574"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="14" fill="#5c6bc0" text-anchor="middle" letter-spacing="0.3">AWS services supported</text>
+
+ <line x1="900" y1="510" x2="900" y2="580" stroke="#3949ab" stroke-width="1" opacity="0.4"/>
+
+ <!-- Stat 4: License -->
+ <text x="1030" y="548"
+ font-family="'Courier New', Courier, monospace"
+ font-size="42" font-weight="700" fill="#ffe082" text-anchor="middle">MIT</text>
+ <text x="1030" y="574"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="14" fill="#5c6bc0" text-anchor="middle" letter-spacing="0.3">Open source license</text>
+
+ <line x1="120" y1="596" x2="1160" y2="596" stroke="#3949ab" stroke-width="1" opacity="0.3"/>
+
+ <!-- URL -->
+ <text x="640" y="622"
+ font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
+ font-size="13" fill="#2a3160" text-anchor="middle" letter-spacing="2.5">floci.io · github.com/hectorvent/floci</text>
+</svg>
diff --git a/logo.svg b/logo.svg
deleted file mode 100644
index 29f0fd6c10..0000000000
--- a/logo.svg
+++ /dev/null
@@ -1,71 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 150" width="500" height="150">
- <defs>
- <!-- Main cloud gradient - warm popcorn white/cream -->
- <linearGradient id="cloudGrad" x1="0%" y1="0%" x2="100%" y2="100%">
- <stop offset="0%" style="stop-color:#fffdf7;stop-opacity:1" />
- <stop offset="50%" style="stop-color:#fef9ee;stop-opacity:1" />
- <stop offset="100%" style="stop-color:#fde68a;stop-opacity:1" />
- </linearGradient>
- <!-- Accent puff gradient - warm amber -->
- <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
- <stop offset="0%" style="stop-color:#fbbf24;stop-opacity:1" />
- <stop offset="100%" style="stop-color:#f59e0b;stop-opacity:1" />
- </linearGradient>
- <!-- Light puff -->
- <linearGradient id="lightPuff" x1="0%" y1="0%" x2="0%" y2="100%">
- <stop offset="0%" style="stop-color:#fef3c7;stop-opacity:1" />
- <stop offset="100%" style="stop-color:#fde68a;stop-opacity:1" />
- </linearGradient>
- <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
- <feGaussianBlur stdDeviation="2" result="blur"/>
- <feComposite in="SourceGraphic" in2="blur" operator="over"/>
- </filter>
- <!-- Cloud outline stroke -->
- <linearGradient id="strokeGrad" x1="0%" y1="0%" x2="100%" y2="100%">
- <stop offset="0%" style="stop-color:#f59e0b;stop-opacity:1" />
- <stop offset="100%" style="stop-color:#d97706;stop-opacity:1" />
- </linearGradient>
- <filter id="softShadow" x="-10%" y="-10%" width="130%" height="140%">
- <feDropShadow dx="0" dy="3" stdDeviation="4" flood-color="#92400e" flood-opacity="0.15"/>
- </filter>
- </defs>
-
- <!-- Main cloud shape -->
- <g filter="url(#softShadow)">
- <!-- Cloud body - smooth overlapping circles -->
- <circle cx="95" cy="88" r="36" fill="url(#cloudGrad)" stroke="#eab308" stroke-width="0.8"/>
- <circle cx="60" cy="92" r="28" fill="url(#cloudGrad)" stroke="#eab308" stroke-width="0.8"/>
- <circle cx="130" cy="92" r="28" fill="url(#cloudGrad)" stroke="#eab308" stroke-width="0.8"/>
- <circle cx="75" cy="68" r="26" fill="url(#cloudGrad)" stroke="#eab308" stroke-width="0.8"/>
- <circle cx="115" cy="66" r="27" fill="url(#cloudGrad)" stroke="#eab308" stroke-width="0.8"/>
- <circle cx="95" cy="56" r="22" fill="url(#cloudGrad)" stroke="#eab308" stroke-width="0.8"/>
- <!-- Smooth fill -->
- <rect x="38" y="88" width="120" height="24" rx="12" fill="url(#cloudGrad)"/>
- </g>
-
- <!-- Floating floccus puffs (scattered small clouds) -->
- <circle cx="152" cy="52" r="8" fill="url(#lightPuff)" opacity="0.7"/>
- <circle cx="145" cy="40" r="6" fill="url(#lightPuff)" opacity="0.5"/>
- <circle cx="160" cy="42" r="5" fill="url(#lightPuff)" opacity="0.4"/>
- <circle cx="30" cy="60" r="6" fill="url(#lightPuff)" opacity="0.5"/>
- <circle cx="22" cy="70" r="5" fill="url(#lightPuff)" opacity="0.35"/>
- <circle cx="155" cy="78" r="4" fill="url(#lightPuff)" opacity="0.3"/>
-
- <!-- Accent sparkle dots (popcorn pop!) -->
- <circle cx="80" cy="48" r="3.5" fill="url(#accentGrad)"/>
- <circle cx="110" cy="44" r="3" fill="url(#accentGrad)" opacity="0.9"/>
- <circle cx="62" cy="62" r="2.5" fill="url(#accentGrad)" opacity="0.7"/>
- <circle cx="128" cy="58" r="2" fill="url(#accentGrad)" opacity="0.6"/>
- <circle cx="95" cy="40" r="2" fill="url(#accentGrad)" opacity="0.8"/>
-
- <!-- Cloud shine highlights -->
- <ellipse cx="80" cy="62" rx="14" ry="8" fill="white" opacity="0.15"/>
- <ellipse cx="105" cy="58" rx="10" ry="6" fill="white" opacity="0.12"/>
- <circle cx="70" cy="72" r="4" fill="white" opacity="0.2"/>
-
- <!-- Text: Floci -->
- <text x="185" y="82" font-size="58" font-weight="800" font-family="'Inter', 'Nunito', 'Segoe UI', system-ui, sans-serif" fill="#78350f" letter-spacing="-2">Floci</text>
-
- <!-- Tagline -->
- <text x="188" y="108" font-size="14" font-family="'Inter', 'Nunito', 'Segoe UI', system-ui, sans-serif" fill="#b45309" letter-spacing="0.5">Light, fluffy, and always free</text>
-</svg>