{"id":37188377,"url":"https://github.com/hotellistat/amps","last_synced_at":"2026-01-14T21:54:26.532Z","repository":{"id":42389245,"uuid":"443090391","full_name":"hotellistat/amps","owner":"hotellistat","description":"AMPS enables asynchronous short and long running message processing for your containers, running as a sidecar next to your already existing workloads","archived":false,"fork":false,"pushed_at":"2025-11-14T11:09:25.000Z","size":51390,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-11-14T11:30:08.210Z","etag":null,"topics":["asynchronous","configurable","kubernetes","messaging","rabbitmq","sidecar"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hotellistat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-12-30T13:57:47.000Z","updated_at":"2025-11-14T07:23:53.000Z","dependencies_parsed_at":"2023-02-16T18:01:50.940Z","dependency_job_id":"ff577e7a-244a-4304-8e87-6e1c5763fa41","html_url":"https://github.com/hotellistat/amps","commit_stats":{"total_commits":195,"total_committers":6,"mean_commits":32.5,"dds":0.2102564102564103,"last_synced_commit":"273949af72cdbe429c988925466e99d8dd0f7602"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"purl":"pkg:github/hotellistat/amps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotellistat%2Famps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotellistat%2Famps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotellistat%2Famps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotellistat%2Famps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hotellistat","download_url":"https://codeload.github.com/hotellistat/amps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotellistat%2Famps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28436239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T21:32:52.117Z","status":"ssl_error","status_checked_at":"2026-01-14T21:32:33.442Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asynchronous","configurable","kubernetes","messaging","rabbitmq","sidecar"],"created_at":"2026-01-14T21:54:25.680Z","updated_at":"2026-01-14T21:54:26.526Z","avatar_url":"https://github.com/hotellistat.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](assets/repository-hero.png)\n\n## Prolog\n\nAMPS arose from our necessity to dynamically scale asynchronous worker queue jobs\nand enabling workers to process several jobs in the same container in parallel.\nWe chose his architecture to have instantaneous worker startup times for a specific maximum amount of parallel jobs without having to wait for a cold start of a container.\n\nAMPS represents a sidecar container that subscribes to a queue such as RabbitMQ and consumes\nmessages from it, with concurrency controlled by RabbitMQ's QoS prefetch mechanism. Upon receiving a message, AMPS\nwill send a HTTP request to the workload container, which will acknowledge that it has received the job by just simply sending back a valid HTTP response code.\nThe workload can then asynchronously work on that message within the workload timeout.\nUpon successful completion of the workload, it will send a `acknowledge` HTTP request back to the AMPS\nsidecar container to finalize the Job completion. A workload can also send back a `reject` request, letting the AMPS container know, that the job could not successfully be processes.\nFurthermore, the AMPS container allows publishing of new jobs through its `publish` endpoint, enabling you to chain several AMPS containers together.\n\nSince AMPS holds an internal state of which job is currently worked on, it knows how to handle and how to timeout concurrently running jobs. Concurrency limits are enforced through RabbitMQ's native QoS prefetch mechanism rather than manual consumer management, providing more reliable and efficient message flow control.\n\n**Note:** AMPS is supposed to do one job well, and one job only. Other popular FaaS-like projects have often seen a huge amount of feature creep over the years, making them outdated, fragile and inefficient.\n\n### Why use HTTP for your workload?\n\nWe chose HTTP as a simple method to convey a job to the workload without the workload having to use any special libraries,\nother than a HTTP server. HTTP also gives us the native ability to run processes/workloads in parallel, without having to do\nany custom process handling on the development side, which of course you can still do if needed.\nThis pattern is well established in the FaaS community, and thus is the reasonable choice for this kind of application.\n\n### Job message structure\n\nAMPS is built, such that it always expects a CloudEvent formatted message body. The spec-version is currently set to `1.0.0`\nand all queue messages should be formatted accordingly.\n\nAMPS also conveys this CloudEvent to the Workload by the **structured content mode**.\nThis means, that it will pack the whole CloudEvent into a JSON and `POST` it to the workload with the `Content-Type: application/json` header.\n\n### Kubernetes\n\nThis container is primarily designed to work in a Kubernetes environment. We can't ensure, that this container will work with other\nsystems such as OpenStack, ECS, etc., although it should be easily possible.\n\n### Scalability\n\nAMPS does not support scaling up and down by itself _at the moment_. To scale AMPS-Workload Pods you will need to choose your own\nscaling solution. We have had great success with using [KEDA](https://keda.sh/) or the HorizontalPodAutoscaler in Kubernetes.\n\nScaling always depends on your specific needs, thus implementing a native scaling solution for AMPS would never cover all use cases. We encourage you to build your own autoscaling system and are open for any features you wish to see implemented. Since we do take care, that the architecture of the project is a modular as possible, it may be possible to build a dynamic autoscaling solution architecture thad does not interfere with the core logic of the container. Stay tuned for RFCs.\n\n## Getting started\n\nAs an example we'll show you how you can use this container as a Sidecar container in your deployment:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: your-deployment-name\n  labels:\n    app: your-deployment-name\nspec:\n  # Scale your worker initially\n  replicas: 10\n  selector:\n    matchLabels:\n      app: your-deployment-name\n  template:\n    metadata:\n      labels:\n        app: your-deployment-name\n    spec:\n      # Create the AMPS sidecar container\n      containers:\n        - name: amps\n          # Fetch the container image. Make sure to pin the version in production\n          image: registry.gitlab.com/hotellistat/amps\n          # Make sure the container is always in a healthy state\n          livenessProbe:\n            httpGet:\n              path: /healthz\n              port: 4000\n            initialDelaySeconds: 3\n            periodSeconds: 3\n          ports:\n            # This will be the port on which the AMPS HTTP server will run on. The port is hardcoded to 4000 for now\n            - containerPort: 4000\n\n          # Environment configuration of the container.\n          # Have a look at /cmd/config/config.go for further configuration details\n          env:\n            - name: BROKER_HOST\n              value: 'amqp://username:password@rabbitmq:5672'\n            - name: BROKER_SUBJECT\n              value: com.yourorg.some-message-queue\n            - name: JOB_TIMEOUT\n              value: '1h'\n            - name: DEBUG\n              value: 'true'\n            - name: MAX_CONCURRENCY\n              value: '20'\n            - name: WORKLOAD_ADDRESS\n              value: 'http://localhost:80'\n\n        # This container represents your workload.\n        # The workload has to have a HTTP server running on the defined port\n        # as configured in the \"WORKLOAD_ADDRESS\" environment variable\n        # (WORKLOAD_ADDRESS env config in the AMPS container)\n        # for the AMPS container to be able to send new messages to the workload.\n        - name: workload\n          image: alpine\n          ports:\n            - containerPort: 80\n```\n\nThis `yaml` schema can of course also be converted into any other k8s object that wraps a Pod/Deployment template.\n\n## Important notes\n\n- Your workload webserver must always instantly respond with a 200 satus code upon receiving a new request from AMPS\n- Make sure to always either acknowlede or reject messages from AMPS such that you don't conjest the job manifest\n\n## Sequence diagram\n\nSometimes a simple diagram explains more than a thousand words:\n\n![](assets/sequence.svg)\n\n## Architectural overview\n\n![](assets/architecture.png)\n\n## Development\n\nDeveloping AMPS is a simple as it gets. Follow these steps:\n\n1. Copy the `.env.template` file and rename it to `.env`\n2. Set the `.env` environment variables to your specification (have a look into [`cmd/amps/config/config.go`](/cmd/amps/config/config.go) for further configuration settings)\n3. Launch a local RabbitMQ server (`docker-compose up rabbitmq`)\n4. Launch the test webserver in the hack folder (`make server`)\n5. Configure the environment variables in the `.env` for your system\n6. Run `make dev`\n\nThe application should just start up and listen for any new messages in the message broker.\n\n## TODO\n\n- [x] Support RabbitMQ\n- [x] Tests\n- [ ] End to End tests\n- [x] Prometheus metrics endpoint\n- [ ] Synchronous mode (FaaS)\n- [x] Configuration should support multiple message brokers\n- [ ] ~~Parallel subscriptions~~\n- [x] Message requeueing and dead letter queueing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhotellistat%2Famps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhotellistat%2Famps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhotellistat%2Famps/lists"}