{"id":17573900,"url":"https://github.com/zgiber/ports","last_synced_at":"2025-10-08T08:10:25.794Z","repository":{"id":85532745,"uuid":"495208552","full_name":"zgiber/ports","owner":"zgiber","description":"Ports","archived":false,"fork":false,"pushed_at":"2022-05-23T09:26:40.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T07:51:37.555Z","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/zgiber.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-23T00:18:03.000Z","updated_at":"2022-05-23T00:18:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"1171744d-fcef-41df-815a-09a39c3b6c42","html_url":"https://github.com/zgiber/ports","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zgiber/ports","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zgiber","download_url":"https://codeload.github.com/zgiber/ports/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fports/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265716306,"owners_count":23816354,"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":[],"created_at":"2024-10-21T21:43:01.150Z","updated_at":"2025-10-08T08:10:20.754Z","avatar_url":"https://github.com/zgiber.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PORTS\n\nService that maintains ports data.\n\n## Overview\n\nThe logical structure of the service is reflected in a number of packages:\n\n- service: core package that maintains the business logic, updating and serving port data.\n- internal/parser: JSON parsing logic that provides the Feed interface that is used by the service to process bulk update of port details.\n- store: embedded key-value store (LMST) that is biased towards fast writes.\n- transport/rest: http service that interfaces the core service providing endpoints for client interaction.\n\nThe project is organised around the core service, which is 'surrounded' by various 'adapters' that depend on the domain constructs defined by the service. Store, and transport are such adapters. This allows the adapters to be replaced by a different mechanism, for example the transport with a new adapter that works from the file system instead of processing http requests.\n\n## Running the service\n\n### Directly (compiled from source)\n\nAssuming that go \u003e= 1.15 is present and you're in the ./cmd directory:\n\n- Download dependencies\n\n```sh\ngo get ./...\n```\n\n- Build the executable\n\n```sh\ngo build -o ports\n```\n\n- Run the service\n\n```sh\n./ports -db_path=\u003cpath-for-database-files\u003e\n```\n\nThe service listens on port 8000 by default, that can be overridden by the `addr` parameter.\n\n### Docker\n\nFrom the project root directory:\n\n- Build the container\n\n```sh\ndocker build . -t ports\n```\n\n- Run the service in the container (exposing port 8000)\n\n```sh\ndocker run --rm --name ports -p:8000:8000 ports\n```\n\n## HTTP Endpoints\n\n### POST /ports\n\nAllows a client to upload a json structure as defined in the original task description. The JSON input is parsed as a stream. Existing entries are overwritten by the provided update.\n\nExample (where ports.json contains the updates):\n\n```sh\ncurl -v 'localhost:8000/ports' -d@ports.json\n```\n\n### GET /ports\n\nAllows a client to retrieve port information. Provides an array of port objects ordered by port UN/LOCODE. Partial or paginated results are retrieved by providing `from_id` and `limit` parameters. If `from_id` is not provided then the first N entry is returned where N is defined by the `limit` parameter. If limit is not provided, then the maximum number of returned entries will be set to 1000.\n\n```curl\ncurl -v 'localhost:8000/ports?from_id=ZWBUQ?limit=2'\n```\n\n```json\n[\n  {\n    \"ID\": \"ZWHRE\",\n    \"Details\": {\n      \"name\": \"Harare\",\n      \"city\": \"Harare\",\n      \"country\": \"Zimbabwe\",\n      \"coordinates\": [\n        31.03351,\n        -17.8251657\n      ],\n      \"province\": \"Harare\",\n      \"timezone\": \"Africa/Harare\",\n      \"unlocs\": [\n        \"ZWHRE\"\n      ]\n    }\n  },\n  {\n    \"ID\": \"ZWUTA\",\n    \"Details\": {\n      \"name\": \"Mutare\",\n      \"city\": \"Mutare\",\n      \"country\": \"Zimbabwe\",\n      \"coordinates\": [\n        32.650351,\n        -18.9757714\n      ],\n      \"province\": \"Manicaland\",\n      \"timezone\": \"Africa/Harare\",\n      \"unlocs\": [\n        \"ZWUTA\"\n      ]\n    }\n  }\n]\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzgiber%2Fports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzgiber%2Fports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzgiber%2Fports/lists"}