{"id":36860116,"url":"https://github.com/usvc/go-server","last_synced_at":"2026-01-12T14:49:22.417Z","repository":{"id":57572587,"uuid":"340123456","full_name":"usvc/go-server","owner":"usvc","description":"Batteries included base server library","archived":false,"fork":false,"pushed_at":"2021-03-29T09:58:19.000Z","size":93,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-15T22:04:26.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/usvc.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}},"created_at":"2021-02-18T17:18:56.000Z","updated_at":"2021-03-29T09:55:38.000Z","dependencies_parsed_at":"2022-08-24T08:40:54.765Z","dependency_job_id":null,"html_url":"https://github.com/usvc/go-server","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/usvc/go-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usvc","download_url":"https://codeload.github.com/usvc/go-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"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":[],"created_at":"2026-01-12T14:49:22.327Z","updated_at":"2026-01-12T14:49:22.394Z","avatar_url":"https://github.com/usvc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `go-server`\n\n[![go version](https://img.shields.io/github/go-mod/go-version/usvc/go-server)](https://github.com/usvc/go-server)\n[![tag github](https://img.shields.io/github/v/tag/usvc/go-server)](https://github.com/usvc/go-server/tags)\n[![build status](https://travis-ci.org/usvc/go-server.svg?branch=master)](https://travis-ci.org/usvc/go-server)\n[![pipeline status](https://gitlab.com/usvc/modules/go/server/badges/master/pipeline.svg)](https://gitlab.com/usvc/modules/go/server/-/commits/master)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/acfc321def02f47b57a2/test_coverage)](https://codeclimate.com/github/usvc/go-server/test_coverage)\n[![Maintainability](https://api.codeclimate.com/v1/badges/acfc321def02f47b57a2/maintainability)](https://codeclimate.com/github/usvc/go-server/maintainability)\n\nA Go package to deal with setting up a cloud-native microservices-ready server\n\n|        |                                                                                        |\n| ------ | -------------------------------------------------------------------------------------- |\n| Github | [https://github.com/usvc/go-server](https://github.com/usvc/go-server)                 |\n| Gitlab | [https://gitlab.com/usvc/modules/go/server](https://gitlab.com/usvc/modules/go/server) | . |\n\n## Why use this\n\nThis server package comes with the following in-built and configured with reasonable defaults:\n\n1. Prometheus metrics\n2. Healthcheck probes\n3. Request identification\n4. Request logging\n5. Cross-Origin Resource Sharing (CORS)\n6. Graceful shutdown handling\n\n## Usage\n\n### Importing\n\n```go\nimport \"github.com/usvc/go-server\"\n```\n\n### Creating a server\n\n```go\npackage main\n\nimport (\n  \"net/http\"\n  \"github.com/usvc/go-server\"\n)\n\nfunc main() {\n  options := server.NewHTTPOptions()\n  mux := http.NewServeMux()\n  // ... other configuration tasks ...\n\ts := server.NewHTTP(options, mux)\n}\n```\n\n### Using a custom logger\n\n```go\n// ...\n  options := server.NewHTTPOptions()\n  options.Loggers.ServerEvent = func(args ...interface{}) {\n    logrus.Debug(args...)\n  }\n  options.Loggers.Request = func(args ...interface{}) {\n    logrus.Trace(args...)\n  }\n// ...\n```\n\n### Using liveness/readiness probes\n\nBoth types of healthchecks implement a similar pattern\n\n```go\n// ...\n  options := server.NewHTTPOptions()\n  // for liveness probes\n  options.LivenessProbe.Handlers = types.HTTPProbeHandlers{\n    func() error {\n      // ... some checks maybe? ...\n      return nil\n    },\n  }\n  // for readiness probes\n  options.ReadinessProbe.Handlers = types.HTTPProbeHandlers{\n    func() error {\n      // ... some checks maybe? ...\n      return nil\n    },\n  }\n// ...\n```\n\n### Using a custom path for probes/metrics\n\n```go\n// ...\n  options := server.NewHTTPOptions()\n  // ... use /not-healthz as the liveness probe endpoint ...\n  options.LivenessProbe.Path = \"/not-healthz\"\n  // ... use /see-whats-inside as the metrics endpoint ...\n  options.Metrics.Path = \"/see-whats-inside\"\n  // ... use /not-healthz as the readiness probe endpoint ...\n  options.ReadinessProbe.Path = \"/not-readyz\"\n// ...\n```\n\n### Password protecting provided paths\n\n```go\n// ...\n  options := server.NewHTTPOptions()\n  // ... protect the liveness probe endpoint with a password...\n  options.LivenessProbe.Password = \"123456\"\n  // ... protect the metrics endpoint with a password...\n  options.Metrics.Password = \"123456\"\n  // ... protect the readiness probe endpoint with a password...\n  options.ReadinessProbe.Password = \"123456\"\n// ...\n```\n\n### Using custom middlewares\n\n```go\n// ...\n  options := server.NewHTTPOptions()\n  options.Middlewares = append(options.Middlewares, func(next http.Handler) http.Handler {\n    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n      // ... custom middleware logic ...\n      next.ServeHTTP(w, r)\n    })\n  })\n// ...\n```\n\n### Disabling features\n\n```go\n// ...\n  options := server.NewHTTPOptions()\n  \n  // to disable CORS\n  options.Disable.CORS = false\n\n  // to disable the liveness probe endpoint from being registered\n  options.Disable.LivenessProbe = false\n\n  // to disable the metrics endpoint from being reigstered\n  options.Disable.Metrics = false\n\n  // to disable the readiness probe endpoint from being registered\n  options.Disable.ReadinessProbe = false\n\n  // to disable the request identification middleware\n  options.Disable.RequestIdentifier = false\n\n  // to disable the request logging middleware\n  options.Disable.RequestLogger = false\n\n  // to disable the syscall signal handler middleware\n  options.Disable.SignalHandling = false\n\n  // to disable the version endpoint from being registered\n  options.Disable.Version = false\n// ...\n```\n\n## Development Runbook\n\n### Getting Started\n\n1. Clone this repository\n2. Run `make deps` to pull in external dependencies\n3. Write some awesome stuff\n4. Run `make test` to ensure unit tests are passing\n5. Push\n\n### Continuous Integration (CI) Pipeline\n\n#### On Github\n\nGithub is used to deploy binaries/libraries because of it's ease of access by other developers.\n\n##### Releasing\n\nReleasing of the binaries can be done via Travis CI.\n\n1. On Github, navigate to the [tokens settings page](https://github.com/settings/tokens) (by clicking on your profile picture, selecting **Settings**, selecting **Developer settings** on the left navigation menu, then **Personal Access Tokens** again on the left navigation menu)\n2. Click on **Generate new token**, give the token an appropriate name and check the checkbox on **`public_repo`** within the **repo** header\n3. Copy the generated token\n4. Navigate to [travis-ci.org](https://travis-ci.org) and access the cooresponding repository there. Click on the **More options** button on the top right of the repository page and select **Settings**\n5. Scroll down to the section on **Environment Variables** and enter in a new **NAME** with `RELEASE_TOKEN` and the **VALUE** field cooresponding to the generated personal access token, and hit **Add**\n\n#### On Gitlab\n\nGitlab is used to run tests and ensure that builds run correctly.\n\n##### Version Bumping\n\n1. Run `make .ssh`\n2. Copy the contents of the file generated at `./.ssh/id_rsa.base64` into an environment variable named **`DEPLOY_KEY`** in **Settings \u003e CI/CD \u003e Variables**\n3. Navigate to the **Deploy Keys** section of the **Settings \u003e Repository \u003e Deploy Keys** and paste in the contents of the file generated at `./.ssh/id_rsa.pub` with the **Write access allowed** checkbox enabled\n\n- **`DEPLOY_KEY`**: generate this by running `make .ssh` and copying the contents of the file generated at `./.ssh/id_rsa.base64`\n\n##### DockerHub Publishing\n\n1. Login to [https://hub.docker.com](https://hub.docker.com), or if you're using your own private one, log into yours\n2. Navigate to [your security settings at the `/settings/security` endpoint](https://hub.docker.com/settings/security)\n3. Click on **Create Access Token**, type in a name for the new token, and click on **Create**\n4. Copy the generated token that will be displayed on the screen\n5. Enter the following varialbes into the CI/CD Variables page at **Settings \u003e CI/CD \u003e Variables** in your Gitlab repository:\n\n- **`DOCKER_REGISTRY_URL`**: The hostname of the Docker registry (defaults to `docker.io` if not specified)\n- **`DOCKER_REGISTRY_USERNAME`**: The username you used to login to the Docker registry\n- **`DOCKER_REGISTRY_PASSWORD`**: The generated access token\n\n## Licensing\n\nCode in this package is licensed under the [MIT license (click to see full text))](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusvc%2Fgo-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusvc%2Fgo-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusvc%2Fgo-server/lists"}