diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0f9f4e4d1..ef6c279af 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,6 +12,7 @@ jobs: runs-on: ubuntu-20.04 env: MIX_ENV: test + CI: true strategy: fail-fast: false matrix: diff --git a/CHANGELOG.md b/CHANGELOG.md index 88c04679b..d61c93213 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ * Improve warning when referencing type from a private module * Rename "Search HexDocs package" modal to "Go to package docs". Support built-in Erlang/OTP apps. + * Document how to use `.erlang.crypt` with ExDoc * Bug fixes * Switch anchor `title` to `aria-label` diff --git a/lib/ex_doc/config.ex b/lib/ex_doc/config.ex index b20debced..cd6811354 100644 --- a/lib/ex_doc/config.ex +++ b/lib/ex_doc/config.ex @@ -21,6 +21,7 @@ defmodule ExDoc.Config do before_closing_head_tag: &__MODULE__.before_closing_head_tag/1, canonical: nil, cover: nil, + debug_info_fn: nil, deps: [], extra_section: nil, extras: [], @@ -50,6 +51,10 @@ defmodule ExDoc.Config do title: nil, version: nil + @typep debug_info_fn_arg :: :init | :clear | {:debug_info, atom(), module(), :file.filename()} + @typep debug_info_fn :: (debug_info_fn_arg -> + :ok | {:ok, (debug_info_fn_arg -> term())} | {:error, term()}) + @type t :: %__MODULE__{ annotations_for_docs: (map() -> list()), api_reference: boolean(), @@ -61,6 +66,7 @@ defmodule ExDoc.Config do before_closing_head_tag: (atom() -> String.t()) | mfa() | map(), canonical: nil | String.t(), cover: nil | Path.t(), + debug_info_fn: nil | debug_info_fn(), deps: [{ebin_path :: String.t(), doc_url :: String.t()}], extra_section: nil | String.t(), extras: list(), @@ -120,7 +126,23 @@ defmodule ExDoc.Config do guess_url(options[:source_url], options[:source_ref] || @default_source_ref) end) + {debug_info_key, options} = Keyword.pop(options, :debug_info_key) + + {debug_info_fn, options} = + case Keyword.pop(options, :debug_info_fn) do + {nil, options} -> Keyword.pop(options, :debug_info_fun) + {debug_info_fn, options} -> {debug_info_fn, options} + end + + debug_info_fn = + cond do + debug_info_fn != nil -> debug_info_fn + debug_info_key != nil -> default_debug_info_fn(debug_info_key) + true -> nil + end + preconfig = %__MODULE__{ + debug_info_fn: debug_info_fn, filter_modules: normalize_filter_modules(filter_modules), groups_for_modules: normalize_groups_for_modules(groups_for_modules), homepage_url: options[:homepage_url], @@ -224,4 +246,18 @@ defmodule ExDoc.Config do defp append_slash(url) do if :binary.last(url) == ?/, do: url, else: url <> "/" end + + defp default_debug_info_fn(key) do + key = + case key do + {_mode, key} -> to_charlist(key) + key -> to_charlist(key) + end + + fn + :init -> :ok + :clear -> :ok + {:debug_info, _mode, _module, _filename} -> key + end + end end diff --git a/lib/ex_doc/retriever.ex b/lib/ex_doc/retriever.ex index aaa30cfbf..64f87ecca 100644 --- a/lib/ex_doc/retriever.ex +++ b/lib/ex_doc/retriever.ex @@ -80,7 +80,7 @@ defmodule ExDoc.Retriever do end defp get_module(module, config) do - with {:docs_v1, _, language, _, _, _metadata, _} = docs_chunk <- docs_chunk(module), + with {:docs_v1, _, language, _, _, _metadata, _} = docs_chunk <- docs_chunk(module, config), {:ok, language} <- ExDoc.Language.get(language, module), %{} = module_data <- language.module_data(module, docs_chunk, config) do {:ok, generate_node(module, module_data, config)} @@ -90,7 +90,11 @@ defmodule ExDoc.Retriever do end end - defp docs_chunk(module) do + defp docs_chunk(module, config) do + if debug_info_fn = config.debug_info_fn do + set_crypto_key_fn(debug_info_fn) + end + result = Code.fetch_docs(module) Refs.insert_from_chunk(module, result) @@ -496,4 +500,17 @@ defmodule ExDoc.Retriever do defp source_link(source, line) do Utils.source_url_pattern(source.url, source.path |> Path.relative_to(File.cwd!()), line) end + + @doc false + def set_crypto_key_fn(crypto_key_fn) do + :beam_lib.clear_crypto_key_fun() + + case :beam_lib.crypto_key_fun(crypto_key_fn) do + {:error, reason} -> + raise Error, "failed to set crypto_key_fun: #{inspect(reason)}" + + other -> + other + end + end end diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index 250d037fb..d1fdbb261 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -100,6 +100,16 @@ defmodule Mix.Tasks.Docs do the "assets" directory in the output path under the name "cover" and the appropriate extension. This option has no effect when using the "html" formatter. + * `:debug_info_key` - The key to be used to decrypt debug info that was encrypted during + compilation. This option will be ignored if `:debug_info_fn` or `:debug_info_fun` is provided. + See [Encrypted debug info](`m:Mix.Tasks.Docs#module-encrypted-debug-info`). + + * `:debug_info_fn` / `:debug_info_fun` - A function that will be provided to + `:beam_lib.crypto_key_fun/1` to decrypt debug info that was encrypted during compilation. If + both `:debug_info_fn` and `:debug_info_fun` are provided, `:debug_info_fun` will be ignored. + If this option is provided, `:debug_info_key` will be ignored. See + [Encrypted debug info](`m:Mix.Tasks.Docs#module-encrypted-debug-info`). + * `:deps` - A keyword list application names and their documentation URL. ExDoc will by default include all dependencies and assume they are hosted on HexDocs. This can be overridden by your own values. Example: `[plug: "https://myserver/plug/"]` @@ -200,6 +210,14 @@ defmodule Mix.Tasks.Docs do where path is either an relative path from the cwd, or an absolute path. The function must return the full URI as it should be placed in the documentation. + ## Encrypted debug info + + If a module is compiled with [encrypted debug info](`:compile.file/2`), ExDoc will not be able to + extract its documentation without preparation. ExDoc supports using `.erlang.crypt` to decrypt + debug information. Consult the + [`.erlang.crypt` section in the `:beam_lib` documentation](`m::beam_lib#module-erlang-crypt`) + for more information. + ## Groups ExDoc content can be organized in groups. This is done via the `:groups_for_extras` diff --git a/test/ex_doc/config_test.exs b/test/ex_doc/config_test.exs index fd348284c..3d2c79357 100644 --- a/test/ex_doc/config_test.exs +++ b/test/ex_doc/config_test.exs @@ -74,4 +74,58 @@ defmodule ExDoc.ConfigTest do assert config.skip_code_autolink_to.("ConfigTest.Hidden.bar/1") refute config.skip_code_autolink_to.("ConfigTest.NotHidden") end + + test "produces a function when a debug_info_key is provided" do + config = ExDoc.Config.build(@project, @version, debug_info_key: "Hunter2") + + assert config.debug_info_fn.(:init) == :ok + assert config.debug_info_fn.(:clear) == :ok + assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"Hunter2" + + config = ExDoc.Config.build(@project, @version, debug_info_key: {:des3_cbc, "Hunter3"}) + + assert config.debug_info_fn.(:init) == :ok + assert config.debug_info_fn.(:clear) == :ok + assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"Hunter3" + end + + test "ignores debug_info_key when debug_info_fn or debug_info_fun is provided" do + config = + ExDoc.Config.build(@project, @version, + debug_info_key: "Hunter2", + debug_info_fn: debug_info_fn(~c"foxtrot") + ) + + assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"foxtrot" + + config = + ExDoc.Config.build(@project, @version, + debug_info_key: "Hunter2", + debug_info_fun: debug_info_fn(~c"tango") + ) + + assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"tango" + end + + test "handles either debug_info_fn or debug_info_fun, but debug_info_fn takes precedence" do + config = + ExDoc.Config.build(@project, @version, + debug_info_fun: debug_info_fn(~c"fun"), + debug_info_fn: debug_info_fn(~c"fn") + ) + + assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"fn" + + config = ExDoc.Config.build(@project, @version, debug_info_fun: debug_info_fn(~c"fun")) + + assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"fun" + end + + defp debug_info_fn(key) do + fn + :init -> :ok + :clear -> :ok + {:debug_info, _mode, _module, _filename} -> key + end + end end diff --git a/test/ex_doc/retriever/erlang_test.exs b/test/ex_doc/retriever/erlang_test.exs index bcba5f3c6..0ce47b464 100644 --- a/test/ex_doc/retriever/erlang_test.exs +++ b/test/ex_doc/retriever/erlang_test.exs @@ -111,6 +111,62 @@ defmodule ExDoc.Retriever.ErlangTest do ~r'Equivalent to ]+>function2\(\[\{test, args\}\]\).*\.' end + test "with encrypted debug_info", c do + erlc( + c, + :debug_info_mod, + ~S""" + -module(debug_info_mod). + -moduledoc("mod docs."). + -export([function1/0]). + -export_type([foo/0]). + + -doc("foo/0 docs."). + -type foo() :: atom(). + + -doc("function1/0 docs."). + -spec function1() -> atom(). + function1() -> ok. + """, + debug_info_key: ~c"SECRET" + ) + + config = ExDoc.Config.build("debug_info_mod", 1, debug_info_key: ~c"SECRET") + + {[mod], []} = Retriever.docs_from_modules([:debug_info_mod], config) + + assert %ExDoc.ModuleNode{ + moduledoc_file: moduledoc_file, + docs: [function1], + id: "debug_info_mod", + module: :debug_info_mod, + title: "debug_info_mod", + typespecs: [foo] + } = mod + + assert DocAST.to_string(mod.doc) =~ "mod docs." + assert DocAST.to_string(function1.doc) =~ "function1/0 docs." + assert DocAST.to_string(foo.doc) =~ "foo/0 docs." + assert moduledoc_file =~ "debug_info_mod.erl" + end + + test "encrypted with tuple key", c do + erlc( + c, + :debug_info_mod2, + ~S""" + -module(debug_info_mod2). + -moduledoc("mod docs."). + """, + debug_info_key: {:des3_cbc, ~c"SECRET"} + ) + + config = ExDoc.Config.build("debug_info_mod2", 1, debug_info_key: {:des3_cbc, "SECRET"}) + + assert {[%ExDoc.ModuleNode{module: :debug_info_mod2}], []} = + Retriever.docs_from_modules([:debug_info_mod2], config) + end + test "module included files", c do erlc(c, :mod, ~S""" -file("module.hrl", 1). @@ -354,6 +410,61 @@ defmodule ExDoc.Retriever.ErlangTest do |> Erlang.autolink_spec(current_module: :mod, current_kfa: {:type, :type, 0}) == "type() :: #a{a :: pos_integer(), b :: non_neg_integer(), c :: atom(), d :: term(), e :: term()}." end + + @tag :ci + test "modules with encrypted debug info", c do + File.cp!("test/fixtures/.erlang.crypt", ".erlang.crypt") + + erlc( + c, + :debug_info_mod, + ~S""" + -module(debug_info_mod). + -moduledoc("mod docs."). + -export([function1/0]). + -export_type([foo/0]). + + -doc("foo/0 docs."). + -type foo() :: atom(). + + -doc("function1/0 docs."). + -spec function1() -> atom(). + function1() -> ok. + """, + debug_info_key: ~c"SECRET" + ) + + {[mod], []} = Retriever.docs_from_modules([:debug_info_mod], %ExDoc.Config{}) + + assert %ExDoc.ModuleNode{ + moduledoc_file: moduledoc_file, + docs: [function1], + id: "debug_info_mod", + module: :debug_info_mod, + title: "debug_info_mod", + typespecs: [foo] + } = mod + + assert DocAST.to_string(mod.doc) =~ "mod docs." + assert DocAST.to_string(function1.doc) =~ "function1/0 docs." + assert DocAST.to_string(foo.doc) =~ "foo/0 docs." + assert moduledoc_file =~ "debug_info_mod.erl" + + erlc( + c, + :debug_info_mod2, + ~S""" + -module(debug_info_mod2). + -moduledoc("mod docs."). + """, + debug_info_key: {:des3_cbc, ~c"PASSWORD"} + ) + + assert {[%ExDoc.ModuleNode{module: :debug_info_mod2}], []} = + Retriever.docs_from_modules([:debug_info_mod2], %ExDoc.Config{}) + + File.rm!(".erlang.crypt") + end end describe "docs_from_modules/2 edoc" do diff --git a/test/ex_doc/retriever_test.exs b/test/ex_doc/retriever_test.exs index 471c75fb0..f4553092d 100644 --- a/test/ex_doc/retriever_test.exs +++ b/test/ex_doc/retriever_test.exs @@ -307,4 +307,14 @@ defmodule ExDoc.RetrieverTest do %{docs: [%{signature: signature}]} = module_node assert signature == "callback_name(arg1, integer, %Date{}, term, t)" end + + test "set_crypto_key_fn/1 raises if it receives an error" do + assert_raise( + Retriever.Error, + "failed to set crypto_key_fun: :badfun", + fn -> + Retriever.set_crypto_key_fn(fn _ -> {:error, :badfun} end) + end + ) + end end diff --git a/test/fixtures/.erlang.crypt b/test/fixtures/.erlang.crypt new file mode 100644 index 000000000..befada42a --- /dev/null +++ b/test/fixtures/.erlang.crypt @@ -0,0 +1,2 @@ +[{debug_info, des3_cbc, debug_info_mod, "SECRET"}, + {debug_info, des3_cbc, [], "PASSWORD"}]. \ No newline at end of file diff --git a/test/test_helper.exs b/test/test_helper.exs index a555ba53f..0b6e5a613 100644 --- a/test/test_helper.exs +++ b/test/test_helper.exs @@ -1,10 +1,12 @@ otp_eep48? = Code.ensure_loaded?(:edoc_doclet_chunks) otp_eep59? = Code.ensure_loaded?(:beam_doc) +ci? = System.get_env("CI") == "true" exclude = [ otp_eep48: not otp_eep48?, otp_eep59: not otp_eep59?, - otp_has_docs: not match?({:docs_v1, _, _, _, _, _, _}, Code.fetch_docs(:array)) + otp_has_docs: not match?({:docs_v1, _, _, _, _, _, _}, Code.fetch_docs(:array)), + ci: not ci? ] ExUnit.start(exclude: Enum.filter(exclude, &elem(&1, 1))) @@ -58,14 +60,20 @@ defmodule TestHelper do beam_docs = docstrings(docs, context) + # not to be confused with the regular :debug_info opt + debug_info_opts = + Enum.filter(opts, fn + {:debug_info, _debug_info} -> true + {:debug_info_key, _debug_info_key} -> true + :encrypt_debug_info -> true + _ -> false + end) + {:ok, module} = :compile.file( String.to_charlist(src_path), - [ - :return_errors, - :debug_info, - outdir: String.to_charlist(ebin_dir) - ] ++ beam_docs + [:return_errors, :debug_info, outdir: String.to_charlist(ebin_dir)] ++ + beam_docs ++ debug_info_opts ) true = Code.prepend_path(ebin_dir)