{"id":26661287,"url":"https://github.com/peter-mghendi/talaria","last_synced_at":"2026-05-15T22:31:09.035Z","repository":{"id":283880709,"uuid":"949601661","full_name":"peter-mghendi/talaria","owner":"peter-mghendi","description":"Fast, lightweight email rendering over gRPC, gRPC-Web, HTTP and Connect.","archived":false,"fork":false,"pushed_at":"2025-03-22T18:51:59.000Z","size":27,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-07T01:32:36.880Z","etag":null,"topics":["connectrpc","grpc","grpc-web","hermes","http"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peter-mghendi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-16T20:07:04.000Z","updated_at":"2025-03-23T05:09:27.000Z","dependencies_parsed_at":"2025-03-22T19:41:37.845Z","dependency_job_id":null,"html_url":"https://github.com/peter-mghendi/talaria","commit_stats":null,"previous_names":["peter-mghendi/talaria"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/peter-mghendi/talaria","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Ftalaria","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Ftalaria/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Ftalaria/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Ftalaria/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-mghendi","download_url":"https://codeload.github.com/peter-mghendi/talaria/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Ftalaria/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33081976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["connectrpc","grpc","grpc-web","hermes","http"],"created_at":"2025-03-25T13:15:51.620Z","updated_at":"2026-05-15T22:31:09.012Z","avatar_url":"https://github.com/peter-mghendi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Talaria\n\nFast, Lightweight Email Rendering Over gRPC, gRPC-Web, HTTP, and Connect\n\nTalaria is a high-performance email rendering service built around the excellent [Hermes](https://github.com/go-hermes/hermes) library. It provides a structured way to generate HTML and plain-text emails using a flexible API that supports **gRPC, gRPC-Web, HTTP, and Connect**.\n\n## Features\n\n- **Multi-Protocol Support** – Works with **gRPC, gRPC-Web, HTTP, and Connect**.\n- **Efficient Email Rendering** – Convert structured email data into **HTML and plain-text** outputs.\n- **Streaming \u0026 Batch Processing** – Supports both **unary and streaming RPCs** for high-throughput rendering.\n- **Lightweight \u0026 Scalable** – Optimized for speed and minimal resource usage.\n- **Fully OpenAPI \u0026 gRPC Compatible** – Can be easily integrated into different backend systems.\n- **Hermes-Based Email Templating** – Uses the [Hermes](https://github.com/go-hermes/hermes) templating engine to generate beautiful emails.\n\n## Installation\n\n### Running with Docker\n\nTalaria is available on both **DockerHub** and **GitHub Container Registry (GHCR)**.\n\n#### **From DockerHub**\n```sh\ndocker run -p 9999:9999 petermghendi/talaria:latest\n```\n\n#### **From GHCR**\n```sh\ndocker run -p 9999:9999 ghcr.io/peter-mghendi/talaria:latest\n```\n\n### Pre-Built Binaries\n\nPre-compiled binaries for major platforms are available on the [Releases Page](https://github.com/peter-mghendi/talaria/releases).\n\n### Running Locally\n\nTalaria is built in **Go** and can be run directly:\n\n```sh\ngit clone https://github.com/peter-mghendi/talaria.git\ncd talaria\ngo run cmd/server/main.go\n```\n\n## Usage\n\n### API Overview\n\n\u003e See [render.proto](https://github.com/peter-mghendi/talaria/blob/main/render/v1/render.proto) for use with gRPC clients.\n\nTalaria exposes the following APIs:\n\n- `Render` – Converts structured email data into HTML and plain text (Unary RPC).\n- `RenderStream` – Handles batch or streaming requests for rendering multiple emails (Bidirectional Streaming RPC).\n\n### Example Request (Unary)\n\nThe unary RPC accepts a `request` consisting a `hermes.Hermes` object and a `hermes.Email` object.\n\n\u003e [!NOTE]\n\u003e Themes are passed in as lowercase strings, i.e. to apply `hermes.Default` pass in `theme: default` and to apply `hermes.Flat` pass in `theme: flat`.\n\u003e `hermes.Default` will be used if no theme is selected.\n\n#### **gRPC**\nUsing `grpcurl`:\n\n```sh\ngrpcurl -plaintext -d @ -proto render/v1/render.proto \\\n    localhost:9999 render.v1.RenderService/Render \u003c render_request.json\n```\n\nExample JSON Payload (`render_request.json`):\n\n```json\n{\n  \"hermes\": {\n    \"theme\": \"default\",\n    \"text_direction\": \"ltr\",\n    \"disable_css_inlining\": false,\n    \"product\": {\n      \"name\": \"Hermes\",\n      \"link\": \"https://example-hermes.com/\",\n      \"logo\": \"http://www.duchess-france.org/wp-content/uploads/2016/01/gopher.png\"\n    }\n  },\n  \"email\": {\n    \"body\": {\n      \"name\": \"Jon Snow\",\n      \"intros\": [\"Welcome to Hermes!\"],\n      \"outros\": [\"Thanks for using Hermes.\"]\n    }\n  }\n}\n```\n\n#### **HTTP (Connect/REST)**\nUsing `curl`:\n\n```sh\ncurl -X POST http://localhost:9999/render.v1.RenderService/Render \\\n    -H \"Content-Type: application/json\" \\\n    -d @render_request.json\n```\n\n### Example Response\n\n```json\n{\n  \"html\": \"\u003chtml\u003e\u003cbody\u003e...\u003c/body\u003e\u003c/html\u003e\",\n  \"text\": \"Welcome to Hermes!\"\n}\n```\n\n## Streaming Requests\n\nFor batch processing or live email previews, Talaria supports bidirectional streaming via `RenderStream`.\n\nThe `identifier` can be any string and is used to corrrelate streaming responses with the original requests.\nThe `request` is the same payload as above, consisting a `hermes.Hermes` object and a `hermes.Email` object.\n\n#### **gRPC Streaming Request**\n```sh\ngrpcurl -plaintext -d '{\"identifier\": \"stream-1\", \"request\": YOUR_JSON_PAYLOAD}' \\\n    -proto render/v1/render.proto \\\n    localhost:9999 render.v1.RenderService/RenderStream\n```\n\n## Load Testing\n\nTo benchmark Talaria's performance:\n\n### **Unary Load Test**\n```sh\nghz --insecure \\\n    --proto render/v1/render.proto \\\n    --call render.v1.RenderService/Render \\\n    -d @render_request.json -n 10000 -c 50 \\\n    localhost:9999\n```\n\n### **Streaming Load Test**\n```sh\nghz --insecure \\\n    --proto render/v1/render.proto \\\n    --call render.v1.RenderService/RenderStream \\\n    -d @render_request.json -n 5000 -c 20 --stream-call-duration 10s \\\n    localhost:9999\n```\n\n## Deployment\n\n### **Using Docker Compose**\nFor easy deployment, you can use `docker-compose`:\n\n```yaml\nversion: \"3\"\nservices:\n  talaria:\n    image: petermghendi/talaria:latest # or ghcr.io/peter-mghendi/talaria:latest\n    ports:\n      - \"9999:9999\"\n    environment:\n      - LOG_LEVEL=info\n```\n\nStart the service:\n\n```sh\ndocker-compose up -d\n```\n\n## Development\n\n### **Building from Source**\n```sh\ngo build -o talaria cmd/server/main.go\n```\n\n### **Running Tests**\n```sh\ngo test ./...\n```\n\n### **Generating Protobuf Files**\n```sh\nbuf lint\nbuf generate\n```\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch (`git switch --create feature-name`).\n3. Commit changes (`git commit --message \"Add feature\"`).\n4. Push the branch (`git push origin feature-name`).\n5. Open a Pull Request.\n\n## License\n\nThis project is licensed under the **MIT License**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-mghendi%2Ftalaria","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-mghendi%2Ftalaria","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-mghendi%2Ftalaria/lists"}