{"id":18871388,"url":"https://github.com/sfomuseum/swifter-protomaps","last_synced_at":"2026-02-16T04:02:39.422Z","repository":{"id":102139210,"uuid":"469955076","full_name":"sfomuseum/swifter-protomaps","owner":"sfomuseum","description":"Swift package providing methods for serving Protomaps tile databases from httpswift/swifter instances.","archived":false,"fork":false,"pushed_at":"2025-01-04T01:51:15.000Z","size":1719,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T00:24:29.781Z","etag":null,"topics":["protomaps","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sfomuseum.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":"2022-03-15T00:52:34.000Z","updated_at":"2025-01-06T19:40:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"9fb67fbf-512b-41c6-98e4-f3d642a21f46","html_url":"https://github.com/sfomuseum/swifter-protomaps","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/sfomuseum/swifter-protomaps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfomuseum%2Fswifter-protomaps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfomuseum%2Fswifter-protomaps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfomuseum%2Fswifter-protomaps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfomuseum%2Fswifter-protomaps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sfomuseum","download_url":"https://codeload.github.com/sfomuseum/swifter-protomaps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfomuseum%2Fswifter-protomaps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273541896,"owners_count":25124056,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"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":["protomaps","swift"],"created_at":"2024-11-08T05:25:41.332Z","updated_at":"2026-02-16T04:02:34.400Z","avatar_url":"https://github.com/sfomuseum.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwifterProtomaps\n\nSwift package providing methods for serving Protomaps tile databases from [httpswift/swifter](https://github.com/httpswift/swifter) instances.\n\n## Motivation\n\nThis package provides a simple `ServeProtomapsTiles` helper method to serve one or more Protomaps tile databases using HTTP `Range` header requests, inclusive of setting any necessary `CORS` headers.\n\nIt was designed for use with an iOS application built around `WKWebKitView` views whose HTML/JavaScript code need to load and render local (on device) Protomaps tiles.\n\nIt is not designed to be a general purpose function for serving files using HTTP `Range` requests. It uses the [swift-pmtiles](https://github.com/sfomuseum/swift-pmtiles) package under the hood.\n\nFor a longer version detailing why we did this please see the [Serving map tiles to yourself using Protomaps and iOS](https://millsfield.sfomuseum.org/blog/2022/03/30/swifter-protomaps/) blog post.\n\n## Example\n\n```\nimport Swifter\nimport SwifterProtomaps\n\ndo {\n            \n\tguard let root = URL(string: \"/path/to/pmtiles\") else {\n\t\traise NSException(name:\"InvalidURL\", reason:\"Invalid URL\", userInfo:nil).raise()\n\t}\n\t\n\tlet port: in_port_t  = 9000\n\t            \n\tvar opts = ServeProtomapsOptions(root: root)\n\topts.AllowOrigins = \"*\"\n\topts.AllowHeaders = \"*\"\n    \n\tlet server = HttpServer()\n\n\tserver[\"/pmtiles/:path\"] = ServeProtomapsTiles(opts)\n\ttry server.start(port)\n\t\n} catch {\n\tprint(\"Server start error: \\(error)\")\n}\n```\n\n_Note: If you define `server` inside a function or a closure and don't persist the variable globally the HTTP server will stop as soon as the variable goes out of scope. This is obvious if you stop to think about it but sometimes these things aren't obvious and you end up burning a lot of cycles figuring it out all over again. Maybe it's just me..._\n\nAnd then in your JavaScript code load and use Protomaps as usual, pointing to the server running on `localhost:9000`:\n\n```\n        const p = new protomaps.PMTiles(\"http://localhost:9000/pmtiles/example.pmtiles\");\n        \n        p.metadata().then(m =\u003e {\n            \n            let bounds_str = m.bounds.split(',')\n            let bounds = [[+bounds_str[1],+bounds_str[0]],[+bounds_str[3],+bounds_str[2]]]\n            \n            layer = new protomaps.LeafletLayer({\n\t            attribution: '',\n        \t    url:p ,\n\t            bounds: bounds,\n            });\n            \n\n            layer.addTo(map);\n        });\n    }\n```\n\nYou can see a working example of this in the [sfomuseum/swifter-protomaps-example](https://github.com/sfomuseum/swifter-protomaps-example) package:\n\n![](docs/images/swifter-protomaps-example.png)\n\n## ServeProtomapsOptions\n\n`ServeProtomapsOptions` defines runtime options for serving Protomaps tiles.\n\n```\npublic struct ServeProtomapsOptions {\n    /// Root is the root directory to serve Protomaps tiles from\n    public var Root: URL\n    /// AllowOrigin is a string containing zero or more allowed origins for CORs requests and responses. Default = \"\".\n    public var AllowOrigins: String\n    /// AllowHeaders is a string containing zero or more allowed headers for CORs requests and responses. Default is \"\".\n    public var AllowHeaders: String\n    /// Logger is an option swift-logging instance for recording errors and warning. Default is nil.\n    public var Logger: Logger?\n    /// Optional string to strip from URL paths before processing. Default is \"\".\n    public var StripPrefix: String\n    /// Optional value to use System.FileDescriptor rather than Foundation.FileHandle to read data. This is necessary when reading from very large Protomaps databases. This should still be considered experimental as in \"It works, but if you find a bug I won't be shocked or anything.\" Default is false.\n    public var UseFileDescriptor: Bool\n}\n```\n\nNote the `UseFileDescriptor` option. If you are trying to serve the 120GB global tileset from an iOS application you will need to enable this. The default behaviour is to use `Foundation.FileHandle` to open files and a 120GB database will trigger POSIX \"Cannot allocate memory\" errors.\n\n## AppTransportSecurity\n\nYou will need to ensure your application has the following `NSAppTransportSecurity` settings:\n\n```\n\t\u003ckey\u003eNSAppTransportSecurity\u003c/key\u003e\n\t\u003cdict\u003e\n\t\t\u003ckey\u003eNSAllowsLocalNetworking\u003c/key\u003e\n\t\t\u003ctrue/\u003e\n\t\t\u003ckey\u003eNSExceptionDomains\u003c/key\u003e\n\t\t\u003cdict\u003e\n\t\t\t\u003ckey\u003elocalhost\u003c/key\u003e\n\t\t\t\u003cdict\u003e\n\t\t\t\t\u003ckey\u003eNSExceptionAllowsInsecureHTTPLoads\u003c/key\u003e\n\t\t\t\t\u003ctrue/\u003e\n\t\t\t\t\u003ckey\u003eNSIncludesSubdomains\u003c/key\u003e\n\t\t\t\t\u003ctrue/\u003e\n\t\t\t\u003c/dict\u003e\n\t\t\u003c/dict\u003e\n\t\u003c/dict\u003e\n```\n\nNote: The use of the `NSExceptionAllowsInsecureHTTPLoads` setting will prevent any application using this package from being accepted by the Apple AppStore. That's not a \"feature\" so much as an acceptable trade-off (for SFO Museum) since this package was developed for local/on-site applications.\n\nThere are other HTTP libraries which support TLS (HTTPS) and which look to be able to run as a background service in an iOS application (notably [hummingbird](https://github.com/hummingbird-project/hummingbird/)) but they have not been tested yet. If you have any experience with or other packages we'd love to hear about it.\n\n## Swift Package Manager\n\nAdd the following entries to your `dependencies` block and any relevant `target` blocks.\n\n```\ndependencies: [\n    \t.package(url: \"https://github.com/sfomuseum/swift-protomaps.git\", from: \"0.1.0\"),\n]\n```\n\n```\n.target(\n\tname: \"{YOUR_TARGET}\",\n\tdependencies: [\n\t\t.product(name: \"SwifterProtomaps\", package: \"swifter-protomaps\")\n\t]\n)\n```\n\n## swifter-protomaps-server\n\n`swifter-protomaps-server` is a minimal HTTP server for serving Protomaps files (using the `SwifterProtomaps` library).\n\n```\n$\u003e swift build \u0026\u0026 ./.build/debug/swifter-protomaps-server --help\nBuilding for debugging...\n[11/11] Applying swifter-protomaps-server\nBuild complete! (0.99s)\nUSAGE: swifter-protomaps-server [--root \u003croot\u003e] [--port \u003cport\u003e] [--verbose \u003cverbose\u003e] [--filedescriptors \u003cfiledescriptors\u003e]\n\nOPTIONS:\n  --root \u003croot\u003e           The parent directory where PMTiles databases should be served from.\n  --port \u003cport\u003e           The port to listen on for new connections (default: 8080)\n  --verbose \u003cverbose\u003e     Enable verbose logging (default: false)\n  --filedescriptors \u003cfiledescriptors\u003e\n                          Use System.FileDescriptor rather than Foundation.FileHandle to read data. This is necessary when reading from very large Protomaps databases. This should\n                          still be considered experimental (default: false)\n  -h, --help              Show help information.\n```\n\n\n## Notes\n\nThis package requires:\n\n* iOS 14.0 or higher\n* MacOS 11.0 or higher.\n\n## See also\n\n* https://github.com/sfomuseum/swift-pmtiles\n* https://github.com/sfomuseum/swifter-protomaps-example\n* https://github.com/sfomuseum/swifter\n* https://github.com/protomaps/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfomuseum%2Fswifter-protomaps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsfomuseum%2Fswifter-protomaps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfomuseum%2Fswifter-protomaps/lists"}