{"id":16828025,"url":"https://github.com/kataras/httpfs","last_synced_at":"2025-08-22T00:42:10.268Z","repository":{"id":57533543,"uuid":"280119135","full_name":"kataras/httpfs","owner":"kataras","description":"Flexible and easy to use HTTP File Server for Go","archived":false,"fork":false,"pushed_at":"2023-11-28T11:47:34.000Z","size":134,"stargazers_count":20,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T01:51:10.210Z","etag":null,"topics":["go","http-file-server","iris"],"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/kataras.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"kataras"}},"created_at":"2020-07-16T10:01:13.000Z","updated_at":"2025-01-11T18:07:08.000Z","dependencies_parsed_at":"2024-02-17T09:44:45.569Z","dependency_job_id":null,"html_url":"https://github.com/kataras/httpfs","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fhttpfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fhttpfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fhttpfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataras%2Fhttpfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kataras","download_url":"https://codeload.github.com/kataras/httpfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248339262,"owners_count":21087214,"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":["go","http-file-server","iris"],"created_at":"2024-10-13T11:24:12.086Z","updated_at":"2025-04-11T03:50:58.323Z","avatar_url":"https://github.com/kataras.png","language":"Go","funding_links":["https://github.com/sponsors/kataras"],"categories":[],"sub_categories":[],"readme":"# HTTP File Server\r\n\r\n[![build status](https://img.shields.io/github/actions/workflow/status/kataras/httpfs/ci.yml?style=for-the-badge)](https://github.com/kataras/httpfs/actions) [![report card](https://img.shields.io/badge/report%20card-a%2B-ff3333.svg?style=for-the-badge)](https://goreportcard.com/report/github.com/kataras/httpfs) [![godocs](https://img.shields.io/badge/go-%20docs-488AC7.svg?style=for-the-badge)](https://godoc.org/github.com/kataras/httpfs)\r\n\r\nLike [http.FileServer](https://pkg.go.dev/net/http?tab=doc#FileServer), plus the following features:\r\n\r\n- Single Page Application **[NEW](_examples/single-page-application)**\r\n- Embedded files through [go-bindata](https://github.com/go-bindata/go-bindata)\r\n- In-memory file system with pre-compressed files **NEW**\r\n- HTTP/2 Push Targets on index requests\r\n- [Fast](https://github.com/kataras/compress) [gzip](https://en.wikipedia.org/wiki/Gzip), [deflate](https://en.wikipedia.org/wiki/DEFLATE), [brotli](https://en.wikipedia.org/wiki/Brotli) and [snappy](https://en.wikipedia.org/wiki/Snappy_(compression)) compression based on the client's needs\r\n- Content [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) and download speed limits\r\n- Customize directory listing by a [template](https://pkg.go.dev/html/template?tab=doc#Template) file or an `index.html`\r\n- Validator for each file per request, e.g. check permissions before serve a file\r\n\r\n## Installation\r\n\r\nThe only requirement is the [Go Programming Language](https://golang.org/dl).\r\n\r\n```sh\r\n$ go get github.com/kataras/httpfs\r\n```\r\n\r\n## Getting Started\r\n\r\nImport the package:\r\n\r\n```go\r\nimport \"github.com/kataras/httpfs\"\r\n```\r\n\r\nThe `httpfs` package is fully compatible with the standard library. Use `FileServer(http.FileSystem, httpfs.Options)` to return a [http.Handler](https://golang.org/pkg/net/http/#Handler) that serves directories and files. \r\n\r\nFor system files you can use the [http.Dir](https://golang.org/pkg/net/http/#Dir):\r\n\r\n```go\r\nfileServer := httpfs.FileServer(http.Dir(\"./assets\"), httpfs.DefaultOptions)\r\n```\r\n\r\nWhere `httpfs.DefaultOptions` looks like this:\r\n\r\n```go\r\nvar DefaultOptions = Options{\r\n\tIndexName:   \"/index.html\",\r\n\tCompress:    true,\r\n\tShowList:    false,\r\n}\r\n```\r\n\r\nTo register a route with a prefix, wrap the handler with the [http.StripPrefix](https://golang.org/pkg/net/http/#StripPrefix):\r\n\r\n```go\r\nfileServer = http.StripPrefix(\"/public/\", fileServer)\r\n```\r\n\r\nRegister the `FileServer` handler:\r\n```go\r\nhttp.Handle(\"/public/\", fileServer)\r\n```\r\n\r\nTo serve files that are translated as Go code, inside the executable program itself, use the [generated](https://github.com/go-bindata/go-bindata) `AssetFile()` instead of `http.Dir`:\r\n\r\n```go\r\nfileServer := httpfs.FileServer(AssetFile(), httpfs.DefaultOptions)\r\n```\r\n\r\nTo cache and compress files(gzip, deflate, snappy and brotli) before server ran, wrap any file system (embedded or physical) with the `MustAsset(http.FileSystem, CacheOptions)` function:\r\n\r\n\r\n```go\r\nvar fileSystem http.FileSystem\r\n\r\n// fileSystem = http.Dir(\"./assets\")\r\nfileSystem = AssetFile()\r\nfileSystem = httpfs.MustCache(fileSystem, httpfs.DefaultCacheOptions)\r\n\r\nfileServer := httpfs.FileServer(fileSystem, httpfs.DefaultOptions)\r\n```\r\n\r\nThe optional `Verbose` call can be used while in development status, it outputs something like that:\r\n\r\n```go\r\nhttpfs.Verbose(fileSystem)\r\n```\r\n\r\n```sh\r\nTime to complete the compression and caching of [3/12] files: 11.0022ms\r\nTotal size reduced from 16.2 kB to:\r\ngzip    (4.6 kB) [71.48%]\r\ndeflate (4.6 kB) [71.82%]\r\nbr      (4.1 kB) [74.46%]\r\nsnappy  (6.5 kB) [59.76%]\r\n```\r\n\r\nRead the available `Options` you can use below:\r\n\r\n```go\r\ndirOptions := httpfs.Options{\r\n\tIndexName: \"/index.html\",\r\n\tPushTargets: map[string][]string{\r\n\t\t\"/\": []string{\r\n\t\t\t\"/public/favicon.ico\",\r\n\t\t\t\"/public/js/main.js\",\r\n\t\t\t\"/public/css/main.css\",\r\n\t\t},\r\n\t},\r\n\tCompress: true,\r\n\tShowList: true,\r\n\tDirList: httpfs.DirListRich(httpfs.DirListRichOptions{\r\n\t\tTmpl:     myHTMLTemplate,\r\n\t\tTmplName: \"dirlist.html\",\r\n\t\tTitle:    \"My File Server\",\r\n\t}),\r\n\tAttachments: httpfs.Attachments{\r\n\t\tEnable: false,\r\n\t\tLimit:  50.0 * httpfs.KB,\r\n\t\tBurst:  100 * httpfs.KB,\r\n\t},\r\n\tAllow: func(w http.ResponseWriter, r *http.Request, name string) bool {\r\n\t\treturn true\r\n\t},\r\n}\r\n```\r\n\r\nThe `httpfs.DirListRich` is just a `DirListFunc` helper function that can be used instead of the default `httpfs.DirList` to improve the look and feel of directory listing. By default it renders the `DirListRichTemplate`. The `DirListRichOptions.Tmpl` field is a [html/template](https://pkg.go.dev/html/template?tab=doc#Template) and it accepts the following page data that you can use in your own template file:\r\n\r\n```go\r\ntype listPageData struct {\r\n\tTitle string\r\n\tFiles []fileInfoData\r\n}\r\n\r\ntype fileInfoData struct {\r\n\tInfo     os.FileInfo\r\n\tModTime  string\r\n\tPath     string\r\n\tRelPath  string\r\n\tName     string\r\n\tDownload bool\r\n}\r\n```\r\n\r\nYou can always perform further customizations on directory listing when `Options.ShowList` field is set to true by setting the `Options.DirList` to a `type DirListFunc` of the following form:\r\n\r\n```go\r\nfunc(w http.ResponseWriter, r *http.Request,\r\n\topts Options, name string, dir http.File) error {\r\n\r\n\t// [...]\r\n}\r\n```\r\n\r\nPlease navigate through [_examples](_examples) directory for more.\r\n\r\n## License\r\n\r\nThis software is licensed under the [MIT License](LICENSE).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkataras%2Fhttpfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkataras%2Fhttpfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkataras%2Fhttpfs/lists"}