{"id":20208779,"url":"https://github.com/palantir/go-baseapp","last_synced_at":"2025-04-05T06:06:55.846Z","repository":{"id":37251461,"uuid":"151643515","full_name":"palantir/go-baseapp","owner":"palantir","description":"A lightweight starting point for Go web servers","archived":false,"fork":false,"pushed_at":"2025-03-27T20:46:20.000Z","size":524,"stargazers_count":74,"open_issues_count":6,"forks_count":12,"subscribers_count":226,"default_branch":"develop","last_synced_at":"2025-03-29T05:06:39.935Z","etag":null,"topics":["golang","lightweight","octo-correct-managed","web-server"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/palantir/go-baseapp","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/palantir.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}},"created_at":"2018-10-04T22:26:31.000Z","updated_at":"2025-03-27T20:46:24.000Z","dependencies_parsed_at":"2023-11-09T00:21:45.555Z","dependency_job_id":"8b6d90d2-d94f-4559-8a38-b893fd4e1ec0","html_url":"https://github.com/palantir/go-baseapp","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Fgo-baseapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Fgo-baseapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Fgo-baseapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Fgo-baseapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/palantir","download_url":"https://codeload.github.com/palantir/go-baseapp/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294536,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["golang","lightweight","octo-correct-managed","web-server"],"created_at":"2024-11-14T05:37:00.981Z","updated_at":"2025-04-05T06:06:55.822Z","avatar_url":"https://github.com/palantir.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-baseapp [![GoDoc](https://godoc.org/github.com/palantir/go-baseapp?status.svg)](http://godoc.org/github.com/palantir/go-baseapp)\n\nA minimal, not-quite-a-framework for building web applications on top of the\nstandard library. It provides:\n\n- A selection of dependencies for logging, metrics, and routing that fit well\n  with the standard library\n- A standard configuration type\n- A basic configurable server type\n- A default (but optional) middleware stack\n\nThis doesn't take the place of frameworks like [echo][], [gin][], or others,\nbut if you prefer to stay close to the standard library for simple\napplications, `go-baseapp` will save you time when starting new projects.\n\n[echo]: https://echo.labstack.com/\n[gin]: https://gin-gonic.github.io/gin/\n\n## Usage\n\nCreate a `baseapp.Server` object, register your handlers, and start the server:\n\n\n```go\nfunc main() {\n    config := baseapp.HTTPConfig{\n        Address: \"127.0.0.1\",\n        Port:    8000,\n    }\n    loggingConfig := baseapp.LoggingConfig{\n        Pretty: true,\n        Level: \"debug\",\n    }\n\n    logger := baseapp.NewLogger(loggingConfig)\n\n    // create a server with default options and no metrics prefix\n    server, err := baseapp.NewServer(config, baseapp.DefaultParams(logger, \"\")...)\n    if err != nil {\n        panic(err)\n    }\n\n    // register handlers\n    server.Mux().Handle(pat.Get(\"/hello\"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        baseapp.WriteJSON(w, http.StatusOK, map[string]string{\n            \"message\": fmt.Sprintf(\"Hello, %s!\", r.FormValue(\"name\")),\n        })\n    }))\n\n    // start the server (blocking)\n    server.Start()\n}\n```\n\n### Example\n\nThe [example package](example/main.go) provides a full server that responds to\n`GET /api/message` requests with a static message from the configuration.\n\nYou can start the server using:\n\n    ./godelw dep\n    ./godelw run example\n\nNavigate to `http://localhost:8000/api/message` to see the output.\n\n## Features and Opinions\n\n`go-baseapp` was designed and is maintained by Palantir's developer tools team.\nWhen developing this project, we had the following in mind:\n\n1. Minimize code and knowledge beyond the standard library. Because we support\n   many applications that have many contributors, we want to minimize the time\n   people spend learning frameworks before being able to add new features or\n   develop new services. To this end, we've used the standard library where we\n   can and picked small dependencies with obvious APIs when we need more\n   features.\n\n3. Allow easy extension. Our opinions in this library form a starting point,\n   but it should be possible to ignore any of them and add your solutions if\n   you disagree with something or it doesn't work in a specific situation.\n\n4. Provide ops-friendly defaults. Our default configuration enables things like\n   request IDs, request and runtime metrics, nice error formatting, and panic\n   recovery.  These are all easy to implement, but are also easy to forget when\n   setting up a new project.\n\nNotably, performance is not a major concern. While we try to avoid decisions\nthat are obviously not performant, our request scale is usually low and it\nmakes more sense to optimize on the factors above.\n\n### Dependencies\n\nOur selected dependencies are ultimately somewhat arbitrary, but have worked\nwell for us and do not include transitive dependencies of their own:\n\n- [rs/zerolog](https://github.com/rs/zerolog) for logging. We like that it has\n  an easy-to-use API, built-in support for `context.Context`, and helpful\n  `net/http` integration via the `hlog` package.\n- [rcrowley/go-metrics](https://github.com/rcrowley/go-metrics) for metrics. We\n  like that it supports many metrics types, isn't coupled to a specific publish\n  method, and has existing integrations with many monitoring and aggregation\n  tools.\n- [goji.io](http://goji.io/) for routing. We like that it provides a minimal\n  API, supports middleware, and integrates nicely with `context.Context`.\n- [bluekeyes/hatpear](https://github.com/bluekeyes/hatpear) for error\n  aggregation. We like that it allows returning errors from HTTP handlers in a\n  way that integrates well with `net/http`.\n\n### Server Options\n\nThe default server configuration (`baseapp.DefaultParams`) does the following:\n\n- Sets a logger\n- Creates a metrics registry with an optional prefix\n- Adds the default middleware to all routes (see below)\n- Configures log timestamps to use UTC and nanosecond precision\n- Improves the formatting of logged errors\n- Enables Go runtime metrics collection\n\nIf you only want some of these options, provide your own set of parameters with\nonly the parts you want; all of the components are exported parts of this\nlibrary or dependencies.\n\n### Graceful Shutdown\n\n`go-baseapp` can be optionally configured to gracefully stop the running server by handling SIGINT and SIGTERM.\n\nThe parameter `ShutdownWaitTime` on the `baseapp.HTTPConfig` struct enables graceful shutdown, and\nalso informs the server how long to wait during the shutdown process before terminating.\n\n### Middleware\n\nThe default middleware stack (`baseapp.DefaultMiddleware`) does the following:\n\n- Adds a logger to the request context\n- Adds a metrics registry to the request context\n- Generates an ID for all requests and sets the `X-Request-ID` header\n- Logs and emits metrics for all requests\n- Handles errors returned by individual route handlers\n- Recovers from panics in individual route handlers\n\nIf you only want some of these features, create your own middleware stack\nselecting the parts you want; all of the components are exported parts of this\nlibrary or dependencies.\n\n### Metrics\n\nIf enabled, the server emits the following metrics:\n\n| metric name | type | definition |\n| ----------- | ---- | ---------- |\n| `server.requests` | `counter` | the count of requests handled by the server |\n| `server.requests.2xx` | `counter` | like `server.requests`, but only counting 2XX status codes |\n| `server.requests.3xx` | `counter` | like `server.requests`, but only counting 3XX status codes |\n| `server.requests.4xx` | `counter` | like `server.requests`, but only counting 4XX status codes |\n| `server.requests.5xx` | `counter` | like `server.requests`, but only counting 5XX status codes |\n| `server.requests.latency` | `timer` | the latency of requests handled by the server |\n| `server.requests.2xx.latency` | `timer` | like `server.requests.latency`, but only counting 2XX status codes |\n| `server.requests.3xx.latency` | `timer` | like `server.requests.latency`, but only counting 3XX status codes |\n| `server.requests.4xx.latency` | `timer` | like `server.requests.latency`, but only counting 4XX status codes |\n| `server.requests.5xx.latency` | `timer` | like `server.requests.latency`, but only counting 5XX status codes |\n| `server.goroutines` | `gauge` | the number of active goroutines |\n| `server.mem.used` | `gauge` | the amount of memory used by the process in bytes |\n\nNote that the `server.requests.latency` timers may be used instead of the basic\n`server.requests` counters, as they include counts and rates in addition to the\nlatency distribution.\n\nThe `appmetrics/emitter/datadog` package provides an easy way to publish metrics to\nDatadog. Timer metrics are reported in nanoseconds. When exporting these\nmetrics from the registry, you may wish to convert the units, for instance by\ncalling `datadog.SetTimerUnit(time.Millisecond)`.\n\nThe `appmetrics/emitter/prometheus` package provids an easy way to expose\nmetrics on a Prometheus-compatible endpoint.\n\n## Contributing\n\nContributions and issues are welcome. For new features or large contributions,\nwe prefer discussing the proposed change on a GitHub issue prior to a PR.\n\nNew functionality should avoid adding new dependencies if possible and should\nbe broadly useful. Feature requests that are specific to certain uses will\nlikely be declined unless they can be redesigned to be generic or optional.\n\nBefore submitting a pull request, please run tests and style checks:\n\n```\n./godelw verify\n```\n\n## License\n\nThis library is made available under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalantir%2Fgo-baseapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpalantir%2Fgo-baseapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalantir%2Fgo-baseapp/lists"}