{"id":34226596,"url":"https://github.com/etwodev/ramchi","last_synced_at":"2026-03-12T02:01:07.609Z","repository":{"id":196150351,"uuid":"694638162","full_name":"etwodev/ramchi","owner":"etwodev","description":"ramchi is an extension to the go-chi HTTP router designed for rapid and modular development of REST APIs.","archived":false,"fork":false,"pushed_at":"2025-10-12T15:59:12.000Z","size":76,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-19T05:56:45.656Z","etag":null,"topics":["go","go-chi","golang","http"],"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/etwodev.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}},"created_at":"2023-09-21T11:54:48.000Z","updated_at":"2025-10-12T15:57:41.000Z","dependencies_parsed_at":"2024-06-21T12:47:05.133Z","dependency_job_id":"131262cc-79ab-4094-b012-82a5e34425ca","html_url":"https://github.com/etwodev/ramchi","commit_stats":null,"previous_names":["etwodev/ramchi"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/etwodev/ramchi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etwodev%2Framchi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etwodev%2Framchi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etwodev%2Framchi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etwodev%2Framchi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etwodev","download_url":"https://codeload.github.com/etwodev/ramchi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etwodev%2Framchi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30412224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["go","go-chi","golang","http"],"created_at":"2025-12-16T00:28:18.180Z","updated_at":"2026-03-12T02:01:07.601Z","avatar_url":"https://github.com/etwodev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ramchi\n\n`ramchi` is an extension to the [go-chi](https://github.com/go-chi/chi) HTTP router designed for rapid and modular development of REST APIs.\n\n## Features\n\n- Modular router and middleware loading system\n- Feature flag support via experimental toggles for safe progressive rollout\n- Easy-to-configure TLS/HTTPS support\n- Graceful shutdown and OS signal handling for clean service termination\n- Built-in, extensible helper packages for requests, responses, crypto, email, and more\n- Automatic configuration file generation and hot loading\n- Integrated structured logging powered by [zerolog](https://github.com/rs/zerolog)\n- Toggle middleware globally via configuration, reducing boilerplate\n\n## Installation\n\nUse Go Modules to install:\n\n```bash\ngo get -u github.com/etwodev/ramchi\n```\n\n## Getting Started\n\nBelow is a minimal example demonstrating how to create and start a `ramchi` server with a modular router and endpoint registration.\n\n```go\npackage main\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\n\t\"github.com/etwodev/ramchi\"\n\t\"github.com/etwodev/ramchi/router\"\n)\n\nfunc main() {\n\ts := ramchi.New()\n\ts.LoadRouter(Routers())\n\ts.Start()\n}\n\n// Define routers with their prefixes and routes\nfunc Routers() []router.Router {\n\treturn []router.Router{\n\t\trouter.NewRouter(\"example\", Routes(), true, nil),\n\t}\n}\n\n// Define individual routes for the router\nfunc Routes() []router.Route {\n\treturn []router.Route{\n\t\trouter.NewGetRoute(\"/demo\", true, false, ExampleGetHandler, nil),\n\t}\n}\n\n// ExampleGetHandler handles GET /example/demo requests\nfunc ExampleGetHandler(w http.ResponseWriter, r *http.Request) {\n\tres, _ := json.Marshal(map[string]string{\"success\": \"ping\"})\n\tw.Header().Set(\"Content-Type\", \"application/json\")\n\tw.WriteHeader(http.StatusCreated)\n\tif _, err := w.Write(res); err != nil {\n\t\t// Handle write error (in production, use proper error logging)\n\t\thttp.Error(w, \"Internal Server Error\", http.StatusInternalServerError)\n\t}\n}\n```\n\n\u003e **Note:** On the first run, `ramchi` auto-generates a default `ramchi.config.json` file in your working directory, which you can customize as needed.\n\n## Configuration\n\nThe behavior of the server and feature toggling is controlled by the `ramchi.config.json` file.\n\n### Default Configuration Example\n\n```json\n{\n  \"port\": \"7000\",\n  \"address\": \"0.0.0.0\",\n  \"experimental\": false,\n  \"logLevel\": \"info\",\n  \"enableTLS\": false,\n  \"tlsCertFile\": \"\",\n  \"tlsKeyFile\": \"\",\n  \"readTimeout\": 15,\n  \"writeTimeout\": 15,\n  \"idleTimeout\": 60,\n  \"maxHeaderBytes\": 1048576,\n  \"shutdownTimeout\": 15,\n  \"enableCORS\": false,\n  \"allowedOrigins\": [\"*\"],\n  \"enableRequestLogging\": false\n}\n```\n\n### Configuration Fields\n\n| Field                  | Type      | Description                                                                 | Default     |\n| ---------------------- | --------- | --------------------------------------------------------------------------- | ----------- |\n| `port`                 | string    | TCP port the server listens on                                              | `\"7000\"`    |\n| `address`              | string    | IP address to bind to                                                       | `\"0.0.0.0\"` |\n| `experimental`         | bool      | Enables or disables experimental feature flags                              | `false`     |\n| `logLevel`             | string    | Log verbosity level (`debug`, `info`, `warn`, `error`, `fatal`, `disabled`) | `\"info\"`    |\n| `enableTLS`            | bool      | Enable HTTPS by providing TLS certificate and key                           | `false`     |\n| `tlsCertFile`          | string    | Path to TLS certificate file (required if `enableTLS` is `true`)            | `\"\"`        |\n| `tlsKeyFile`           | string    | Path to TLS key file (required if `enableTLS` is `true`)                    | `\"\"`        |\n| `readTimeout`          | int       | Max seconds allowed to read incoming requests                               | `15`        |\n| `writeTimeout`         | int       | Max seconds allowed to write responses                                      | `15`        |\n| `idleTimeout`          | int       | Max seconds to keep idle HTTP connections open                              | `60`        |\n| `maxHeaderBytes`       | int       | Maximum size in bytes for HTTP headers                                      | `1048576`   |\n| `shutdownTimeout`      | int       | Timeout in seconds for graceful server shutdown                             | `15`        |\n| `enableCORS`           | bool      | Automatically enables Cross-Origin Resource Sharing (CORS) middleware       | `false`     |\n| `allowedOrigins`       | \\[]string | List of allowed origins for CORS (e.g., `[\"*\"]`, `[\"https://example.com\"]`) | `[\"*\"]`     |\n| `enableRequestLogging` | bool      | Enables HTTP request logging middleware globally                            | `false`     |\n\n## Togglable Middleware\n\nEnable built-in middleware globally using config flags without manual registration:\n\n| Middleware          | Config Flag            | Description                                      |\n| ------------------- | ---------------------- | ------------------------------------------------ |\n| **CORS**            | `enableCORS`           | Adds permissive or restricted CORS headers       |\n| **Request Logging** | `enableRequestLogging` | Logs incoming HTTP requests with structured logs |\n\n\u003e For fine-grained control (middleware order, conditional logic), register middleware manually using `LoadMiddleware()`.\n\n## Accessing Configuration in Code\n\nYou can access configuration values in your application via the `config` package:\n\n```go\nimport c \"github.com/etwodev/ramchi/v2/config\"\n\nport := c.Port()           // e.g. \"7000\"\naddr := c.Address()        // e.g. \"0.0.0.0\"\n\nif c.Experimental() {\n\t// Enable or disable experimental features accordingly\n}\n\nif c.EnableTLS() {\n\tcert := c.TLSCertFile()\n\tkey := c.TLSKeyFile()\n\t// Use cert and key for HTTPS server setup\n}\n```\n\n## Logging\n\n`ramchi` integrates [zerolog](https://github.com/rs/zerolog) for structured, leveled logging:\n\n* Log levels controlled via `logLevel` config (`debug`, `info`, `warn`, `error`, `fatal`, `disabled`)\n* Console-friendly output by default, but pluggable to other loggers if needed\n* Logs contextual information: server name, HTTP method, route, middleware names, error stack traces\n* Logs graceful shutdown steps, warnings, and fatal errors\n\n## Middleware \u0026 Routing Best Practices\n\n* Organize routes modularly using `router.Router` instances grouped by prefixes.\n* Respect feature flags by setting the `Experimental` flag on routes/middleware.\n* Use middleware chaining to add cross-cutting concerns like authentication, CORS, logging.\n* Use the status flag to disable routes/middleware temporarily without deleting code.\n\n## TLS Support\n\nTo serve over HTTPS:\n\n1. Set `\"enableTLS\": true` in `ramchi.config.json`.\n2. Provide valid paths to `\"tlsCertFile\"` and `\"tlsKeyFile\"` for your SSL certificate and private key.\n3. Restart your server.\n\n`ramchi` will handle HTTPS setup automatically.\n\n## Extending ramchi with Helpers\n\n`ramchi` includes utility helper packages to accelerate development:\n\n| Helper Package        | Description                                                |\n| --------------------- | ---------------------------------------------------------- |\n| `helpers/request.go`  | Utilities for HTTP requests (client IP extraction, params) |\n| `helpers/response.go` | JSON encoding, error handling, standardized responses      |\n| `helpers/crypto.go`   | Cryptographic helpers: hashing, encryption utilities       |\n| `helpers/email.go`    | Email templating and sending utilities                     |\n| `helpers/strings.go`  | String manipulation (padding, truncation, sanitization)    |\n| `helpers/encoding.go` | Encoding helpers (hex, base64 conversions)                 |\n\nFeel free to extend or create your own helper packages and contribute back.\n\n## Contribution Guidelines\n\nContributions, feature requests, and bug reports are welcome! Please:\n\n* Fork the repository\n* Create a feature branch (`git checkout -b feature-name`)\n* Write tests for your changes\n* Submit a Pull Request describing your improvements\n* Open issues for discussion before implementing breaking changes\n\n## Example Advanced Usage\n\nHere's an example of grouping multiple routers and adding middleware.\nOf course, in reality, you would put your routes in a separate package for brevity:\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/example/project/middleware/logger\"\n\n\t\"github.com/etwodev/ramchi\"\n\t\"github.com/etwodev/ramchi/router\"\n)\n\nfunc main() {\n\ts := ramchi.New()\n\ts.LoadMiddleware(Middlewares())\n\ts.LoadRouter(Routers())\n\ts.Start()\n}\n\nfunc Routers() []router.Router {\n\treturn []router.Router{\n\t\trouter.NewRouter(\"api/v1\", apiV1Routes(), true, nil),\n\t\trouter.NewRouter(\"admin\", adminRoutes(), true, nil),\n\t}\n}\n\nfunc Middlewares() []middleware.Middleware {\n\treturn []middleware.Middleware{\n\t\tmiddleware.NewMiddleware(logger.Middleware(), \"logger\", true, false),\n\t}\n}\n\nfunc apiV1Routes() []router.Route {\n\treturn []router.Route{\n\t\trouter.NewGetRoute(\"/users\", true, false, usersHandler, nil),\n\t\trouter.NewPostRoute(\"/users\", true, false, createUserHandler, nil),\n\t}\n}\n\nfunc adminRoutes() []router.Route {\n\treturn []router.Route{\n\t\trouter.NewGetRoute(\"/dashboard\", true, false, adminDashboardHandler, nil),\n\t}\n}\n```\n\n## Contact and Support\n\nFor questions, discussions, or support, please open an issue.\n\n## License\n\nMIT License © Etwodev\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetwodev%2Framchi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetwodev%2Framchi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetwodev%2Framchi/lists"}