{"id":20081558,"url":"https://github.com/hexpm/hex_core","last_synced_at":"2025-05-15T05:06:21.776Z","repository":{"id":30020804,"uuid":"123579892","full_name":"hexpm/hex_core","owner":"hexpm","description":"Reference implementation of Hex specifications.","archived":false,"fork":false,"pushed_at":"2024-12-03T13:29:35.000Z","size":547,"stargazers_count":100,"open_issues_count":12,"forks_count":33,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-08T01:56:41.267Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Erlang","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/hexpm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-03-02T13:04:14.000Z","updated_at":"2025-03-11T07:25:56.000Z","dependencies_parsed_at":"2024-02-29T14:44:25.868Z","dependency_job_id":"2a8fb0a3-81c4-45c7-b07c-8f071ffce26a","html_url":"https://github.com/hexpm/hex_core","commit_stats":{"total_commits":287,"total_committers":24,"mean_commits":"11.958333333333334","dds":"0.27177700348432055","last_synced_commit":"affc3f7435c45445551cfa9a3e27b14659e00229"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexpm%2Fhex_core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexpm%2Fhex_core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexpm%2Fhex_core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexpm%2Fhex_core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexpm","download_url":"https://codeload.github.com/hexpm/hex_core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036843,"owners_count":22003654,"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-11-13T15:39:27.582Z","updated_at":"2025-05-15T05:06:16.766Z","avatar_url":"https://github.com/hexpm.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hex_core\n\n[![Build Status](https://github.com/hexpm/hex_core/actions/workflows/main.yml/badge.svg)](https://github.com/hexpm/hex_core/actions/workflows/main.yml)\n\nReference implementation of Hex specifications: \u003chttps://github.com/hexpm/specifications\u003e.\n\n## Usage\n\nLet's use default config for now. See \"Configuration\" section below for customization.\n\n```erlang\nConfig = hex_core:default_config().\n```\n\n**WARNING** The built-in httpc-based HTTP client adapter has insecure default settings\nand thus it is not recommended for usage, in particular for API write operations.\nUse HTTP clients with secure defaults like [hackney](https://hex.pm/packages/hackney) and [Mint](https://hex.pm/packages/mint).\nSee \"Configuration\" and \"Wrapper Module\" sections for more information on customising your usage of `hex_core`.\n\n### Repository\n\nGet all package names:\n\n```erlang\n\u003e hex_repo:get_names(Config).\n{ok,{200, ...,\n     #{packages =\u003e [\n           #{name =\u003e \u003c\u003c\"package1\"\u003e\u003e},\n           #{name =\u003e \u003c\u003c\"package2\"\u003e\u003e},\n           ...]}}}\n```\n\nGet all package versions from repository:\n\n```erlang\n\u003e hex_repo:get_versions(Config).\n{ok,{200, ...,\n     #{packages =\u003e [[\n           #{name =\u003e \u003c\u003c\"package1\"\u003e\u003e, retired =\u003e [], versions =\u003e [\u003c\u003c\"1.0.0\"\u003e\u003e]},\n           #{name =\u003e \u003c\u003c\"package2\"\u003e\u003e, retired =\u003e [], versions =\u003e [\u003c\u003c\"0.5.0\"\u003e\u003e]},\n           ...]}}}\n```\n\nGet package releases from repository:\n\n```erlang\n\u003e hex_repo:get_package(Config, \u003c\u003c\"package1\"\u003e\u003e).\n{ok,{200, ...,\n     #{releases =\u003e [\n           #{checksum =\u003e ..., version =\u003e \u003c\u003c\"0.5.0\"\u003e\u003e, dependencies =\u003e []}],\n           #{checksum =\u003e ..., version =\u003e \u003c\u003c\"1.0.0\"\u003e\u003e, dependencies =\u003e []}],\n           ...]}}}\n```\n\n### API\n\nFor a full list of all parameters and returned objects for the API, check out the API docs: \u003chttps://github.com/hexpm/specifications/blob/master/http_api.md\u003e.\n\nGet package from HTTP API:\n\n```erlang\n\u003e hex_api_package:get(Config, \u003c\u003c\"package1\"\u003e\u003e).\n{ok, {200, ...,\n    #{\n        \u003c\u003c\"name\"\u003e\u003e =\u003e \u003c\u003c\"package1\"\u003e\u003e,\n        \u003c\u003c\"meta\"\u003e\u003e =\u003e #{\n           \u003c\u003c\"description\"\u003e\u003e =\u003e ...,\n           \u003c\u003c\"licenses\"\u003e\u003e =\u003e ...,\n           \u003c\u003c\"links\"\u003e\u003e =\u003e ...,\n           \u003c\u003c\"maintainers\"\u003e\u003e =\u003e ...,\n        },\n        ...,\n        \u003c\u003c\"releases\"\u003e\u003e =\u003e [\n            #{\u003c\u003c\"url\"\u003e\u003e =\u003e ..., \u003c\u003c\"version\"\u003e\u003e =\u003e \u003c\u003c\"0.5.0\"\u003e\u003e}],\n            #{\u003c\u003c\"url\"\u003e\u003e =\u003e ..., \u003c\u003c\"version\"\u003e\u003e =\u003e \u003c\u003c\"1.0.0\"\u003e\u003e}],\n            ...\n        ]\n    }}}\n```\n\nGet package tarball:\n\n```erlang\n{ok, {200, _, Tarball}} = hex_repo:get_tarball(Config, \u003c\u003c\"package1\"\u003e\u003e, \u003c\u003c\"1.0.0\"\u003e\u003e).\n```\n\nPublish package tarball:\n\n```erlang\n{ok, {200, _Headers, _Body} = hex_api_package:publish(Config, Tarball).\n```\n\n### Package tarballs\n\nUnpack package tarball:\n\n```erlang\n{ok, #{outer_checksum := Checksum, contents := Contents, metadata := Metadata}} = hex_tarball:unpack(Tarball, memory).\n```\n\nRemember to verify the outer tarball checksum against the registry checksum\nreturned from `hex_repo:get_package(Config, Package)`.\n\nCreate package tarball:\n\n```erlang\n{ok, #{tarball := Tarball,\n       inner_checksum := InnerChecksum,\n       outer_checksum := OuterChecksum}} = hex_tarball:create(Metadata, Contents).\n```\n\n## Configuration\n\nThe default configuration, provided by `hex_core:default_config/0`, uses built-in httpc-based adapter and Hex.pm APIs:\n\u003chttps://hex.pm/api\u003e and \u003chttps://repo.hex.pm\u003e.\n\nHTTP client configuration can be overridden as follows:\n\n```erlang\nConfig = maps:merge(hex_core:default_config(), #{\n  http_adapter =\u003e {my_hackney_adapter, my_hackney_adapter_config},\n  http_user_agent_fragment =\u003e \u003c\u003c\"(my_app/0.1.0) (hackney/1.12.1) \"\u003e\u003e\n}),\nhex_repo:get_names(Config).\n\n%% my_hackney_adapter.erl\n-module(my_hackney_adapter).\n-behaviour(hex_http).\n-exports([request/5]).\n\nrequest(Method, URI, ReqHeaders, Body, AdapterConfig) -\u003e\n    %% ...\n```\n\nSee the [`hex_core` module](src/hex_core.erl) for more information about the configuration.\n\n## Wrapper Module\n\nIt's recommended to write a wrapper module because a lot of decisions are left to the user, e.g.:\nwhere to get configuration from, how to handle caching, failures etc.\n\nFor a sample, see: [`examples/myapp_hex.erl`](examples/myapp_hex.erl). Here's an excerpt:\n\n```erlang\n-module(myapp_hex).\n-export([\n    get_api_package/1,\n    get_repo_tarball/2,\n    get_repo_versions/0\n]).\n\n%%====================================================================\n%% API functions\n%%====================================================================\n\nget_api_package(Name) -\u003e\n      case hex_api_package:get(config(), Name) of\n          {ok, {200, _Headers, Payload}} -\u003e\n              {ok, Payload};\n\n          Other -\u003e\n              Other\n      end.\n\nget_repo_versions() -\u003e\n      case hex_repo:get_versions(config()) of\n          {ok, {200, _Headers, Payload}} -\u003e\n              {ok, maps:get(packages, Payload)};\n\n          Other -\u003e\n              Other\n      end.\n\n%%====================================================================\n%% Internal functions\n%%====================================================================\n\nconfig() -\u003e\n    Config1 = hex_core:default_config(),\n    Config2 = put_http_config(Config1),\n    Config3 = maybe_put_api_key(Config2),\n    Config3.\n\nput_http_config(Config) -\u003e\n    maps:put(http_user_agent_fragment, \u003c\u003c\"(myapp/1.0.0) (httpc)\"\u003e\u003e, Config).\n\nmaybe_put_api_key(Config) -\u003e\n    case os:getenv(\"HEX_API_KEY\") of\n        false -\u003e Config;\n        Key -\u003e maps:put(api_key, Key, Config)\n    end.\n```\n\n## Installation\n\n### Rebar3\n\nAdd to `rebar.config`:\n\n```erlang\n{deps, [\n  {hex_core, \"0.11.0\"}\n]}\n```\n\n### Mix\n\nAdd to `mix.exs`:\n\n```elixir\ndefp deps do\n  [\n    {:hex_core, \"~\u003e 0.11.0\"}\n  ]\nend\n```\n\n## Development\n\n* Run `rebar3 as dev compile` to re-generate protobuf files\n* Run `rebar3 as test proper` for property-based tests\n* Run `rebar3 ex_doc` to generate documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexpm%2Fhex_core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexpm%2Fhex_core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexpm%2Fhex_core/lists"}