From 60db39df139fa1abf09e3237a5a058672b53f851 Mon Sep 17 00:00:00 2001 From: Mikael Fangel <34864484+MikaelFangel@users.noreply.github.com> Date: Wed, 8 May 2024 13:53:54 +0200 Subject: [PATCH] docs: wrote initial function an module docs --- lib/incident_api.ex | 69 +++++++++++++++++++++++++++++++-------------- lib/logpoint_api.ex | 5 ++++ lib/search_api.ex | 51 ++++++++++++++++++++------------- 3 files changed, 85 insertions(+), 40 deletions(-) diff --git a/lib/incident_api.ex b/lib/incident_api.ex index 123fe40..79411cd 100644 --- a/lib/incident_api.ex +++ b/lib/incident_api.ex @@ -1,82 +1,94 @@ defmodule LogpointApi.IncidentApi do @moduledoc """ This module provides an implementation of the Logpoint Incident API. - - ## Modules - - - `TimeRange` : A struct used to represent a time range. - - `Incident` : A struct used to represent an incident. - - `IncidentComment` : A struct used to represent an incident comment. - - `IncidentCommentData` : A struct used to represent incident comment data. - - `IncidentIDs` : A struct used to represent incident IDs. - - ## Public Functions - - - `get_incidents/3` : Retrieves incidents within a specified time range. - - `get_data_from_incident/3` : Retrieves data from a specific incident. - - `get_incident_states/3` : Retrieves incident states within a specified time range. - - `get_users/2` : Retrieves user data. - - `add_comments/3` : Adds comments to an incident. - - `assign_incidents/4` : Assigns incidents to a user. - - `resolve_incidents/3` : Resolves incidents. - - `reopen_incidents/3` : Reopens incidents. - - `close_incidents/3` : Closes incidents. """ alias LogpointApi.Credential - alias LogpointApi.IncidentApi.{Incident, IncidentComment, IncidentCommentData, IncidentIDs, TimeRange} defmodule TimeRange do + @moduledoc """ + Struct representing a time range with timestamps in epoch. + """ @derive {Jason.Encoder, only: [:version, :ts_from, :ts_to]} defstruct [:ts_from, :ts_to, version: "0.1"] end defmodule Incident do + @moduledoc """ + Struct used to fetch an incident. + """ @derive {Jason.Encoder, only: [:incident_obj_id, :incident_id]} defstruct [:incident_obj_id, :incident_id] end defmodule IncidentComment do + @moduledoc """ + Struct to add comments to a particular incident. + """ @derive {Jason.Encoder, only: [:_id, :comments]} defstruct _id: "", comments: [] end defmodule IncidentCommentData do + @moduledoc """ + Struct to add comments to a list of incidents using the `IncidentComment` struct. + """ @derive {Jason.Encoder, only: [:version, :states]} defstruct version: "0.1", states: [%IncidentComment{}] end defmodule IncidentIDs do + @moduledoc """ + Struct that represents a list of incidents. + """ @derive {Jason.Encoder, only: [:version, :incident_ids]} defstruct version: "0.1", incident_ids: [] end + @doc """ + Get all incidents within a given time range. + """ @spec get_incidents(String.t(), Credential.t(), TimeRange.t()) :: {:ok, map()} | {:error, String.t()} def get_incidents(ip, credential, %TimeRange{} = time_range), do: get_incident_information(ip, "/incidents", credential, time_range) + @doc """ + Get a specific incident and its related data. + """ @spec get_data_from_incident(String.t(), Credential.t(), Incident.t()) :: {:ok, map()} | {:error, String.t()} def get_data_from_incident(ip, credential, %Incident{} = incident), do: get_incident_information(ip, "/get_data_from_incident", credential, incident) + @doc """ + Get the states of incidents within a specific time range. + """ @spec get_incident_states(String.t(), Credential.t(), TimeRange.t()) :: {:ok, map()} | {:error, String.t()} def get_incident_states(ip, credential, %TimeRange{} = time_range), do: get_incident_information(ip, "/incident_states", credential, time_range) + @doc """ + Get users. + """ @spec get_users(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()} def get_users(ip, credential) do payload = make_payload(credential) make_request(ip, "/get_users", :get, payload) end + @doc """ + Add comments to a list of incidents. + """ @spec add_comments(String.t(), Credential.t(), IncidentCommentData.t()) :: {:ok, map()} | {:error, String.t()} def add_comments(ip, credential, %IncidentCommentData{} = incident_comment_data), do: update_incident_state(ip, "/add_incident_comment", credential, incident_comment_data) + @doc """ + Assign or re-assign a list of incidents. + """ @spec assign_incidents(String.t(), Credential.t(), IncidentIDs.t(), String.t()) :: {:ok, map()} | {:error, String.t()} def assign_incidents(ip, credential, %IncidentIDs{} = incident_ids, assignee_id) do @@ -84,21 +96,31 @@ defmodule LogpointApi.IncidentApi do update_incident_state(ip, "/assign_incident", credential, payload) end + @doc """ + Resolve a list of incidents. + """ @spec resolve_incidents(String.t(), Credential.t(), IncidentIDs.t()) :: {:ok, map()} | {:error, String.t()} def resolve_incidents(ip, credential, %IncidentIDs{} = incident_ids), do: update_incident_state(ip, "/resolve_incident", credential, incident_ids) + @doc """ + Reopen a list of incidents. + """ @spec reopen_incidents(String.t(), Credential.t(), IncidentIDs.t()) :: {:ok, map()} | {:error, String.t()} def reopen_incidents(ip, credential, %IncidentIDs{} = incident_ids), do: update_incident_state(ip, "/reopen_incident", credential, incident_ids) + @doc """ + Close a list of incidents. + """ @spec close_incidents(String.t(), Credential.t(), IncidentIDs.t()) :: {:ok, map()} | {:error, String.t()} def close_incidents(ip, credential, %IncidentIDs{} = incident_ids), do: update_incident_state(ip, "/close_incident", credential, incident_ids) + @doc false @spec update_incident_state(String.t(), String.t(), Credential.t(), map()) :: {:ok, map()} | {:error, String.t()} defp update_incident_state(ip, path, credential, request_data) do @@ -106,6 +128,7 @@ defmodule LogpointApi.IncidentApi do make_request(ip, path, :post, payload) end + @doc false @spec get_incident_information(String.t(), String.t(), Credential.t(), map()) :: {:ok, map()} | {:error, String.t()} defp get_incident_information(ip, path, credential, request_data) do @@ -113,6 +136,7 @@ defmodule LogpointApi.IncidentApi do make_request(ip, path, :get, payload) end + @doc false @spec make_request(String.t(), String.t(), atom(), String.t()) :: {:ok, map()} | {:error, String.t()} defp make_request(ip, path, method, payload) do url = build_url(ip, path) @@ -132,9 +156,11 @@ defmodule LogpointApi.IncidentApi do end end + @doc false @spec build_url(String.t(), String.t()) :: String.t() defp build_url(ip, path), do: "https://" <> ip <> path + @doc false @spec make_payload(Credential.t(), map()) :: String.t() defp make_payload(%Credential{} = credential, request_data) do %{ @@ -145,6 +171,7 @@ defmodule LogpointApi.IncidentApi do |> Jason.encode!() end + @doc false @spec make_payload(Credential.t()) :: String.t() defp make_payload(%Credential{} = credential) do %{ diff --git a/lib/logpoint_api.ex b/lib/logpoint_api.ex index 2c9a2fe..449fb2d 100644 --- a/lib/logpoint_api.ex +++ b/lib/logpoint_api.ex @@ -1,5 +1,10 @@ defmodule LogpointApi do + @moduledoc false + defmodule Credential do + @moduledoc """ + Struct representing credentials used for authorization. + """ defstruct [:username, :secret_key] end end diff --git a/lib/search_api.ex b/lib/search_api.ex index 2dcbcb4..ae6fc9b 100644 --- a/lib/search_api.ex +++ b/lib/search_api.ex @@ -1,25 +1,6 @@ defmodule LogpointApi.SearchApi do @moduledoc """ This module provides an implementation of the Logpoint search API. - - ## Modules - - - `Query` : A struct used to represent a search query. - - `SearchID` : A struct used to represent a search ID. - - ## Constants - - - `@allowed_types` : A list of allowed types for data retrieval. - - ## Public Functions - - - `get_user_timezone/2` : Retrieves user timezone data. - - `get_logpoints/2` : Retrieves logpoints data. - - `get_repos/2` : Retrieves repositories data. - - `get_devices/2` : Retrieves devices data. - - `get_livesearches/2` : Retrieves live searches data. - - `get_search_id/3` : Creates a search in Logpoint and returns the JSON object. - - `get_search_result/3` : Retrieves search results for a given search ID. """ alias LogpointApi.Credential @@ -28,45 +9,73 @@ defmodule LogpointApi.SearchApi do @allowed_types ["user_preference", "loginspects", "logpoint_repos", "devices", "livesearches"] defmodule Query do + @moduledoc """ + Struct representing a Logpoint search query. + """ @derive {Jason.Encoder, only: [:query, :time_range, :limit, :repos]} defstruct [:query, :time_range, :limit, :repos] end defmodule SearchID do + @moduledoc """ + Struct representing a search id. + """ @derive {Jason.Encoder, only: [:search_id]} defstruct [:search_id] end + @doc """ + Get the current users time zone information. + """ @spec get_user_timezone(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()} def get_user_timezone(ip, credential), do: get_allowed_data(ip, credential, "user_preference") + @doc """ + Get all logpoints of a Logpoint instance. + """ @spec get_logpoints(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()} def get_logpoints(ip, credential), do: get_allowed_data(ip, credential, "loginspects") + @doc """ + Get the repos of an instance. + """ @spec get_repos(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()} def get_repos(ip, credential), do: get_allowed_data(ip, credential, "logpoint_repos") + @doc """ + Get the devices of the instance. + """ @spec get_devices(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()} def get_devices(ip, credential), do: get_allowed_data(ip, credential, "devices") + @doc """ + Get all live search on a machine. + """ @spec get_livesearches(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()} def get_livesearches(ip, credential), do: get_allowed_data(ip, credential, "livesearches") + @doc """ + Create a search and get its search id. + """ @spec get_search_id(String.t(), Credential.t(), Query.t()) :: {:ok, map()} | {:error, String.t()} def get_search_id(ip, credential, %Query{} = query), do: get_search_logs(ip, credential, query) + @doc """ + Retrieve the search result of a specific search id. + """ @spec get_search_result(String.t(), Credential.t(), SearchID.t()) :: {:ok, map()} | {:error, String.t()} def get_search_result(ip, credential, %SearchID{} = search_id), do: get_search_logs(ip, credential, search_id) + @doc false @spec make_request(String.t(), String.t(), String.t()) :: {:ok, map()} | {:error, String.t()} defp make_request(ip, path, payload) do url = build_url(ip, path) @@ -86,21 +95,25 @@ defmodule LogpointApi.SearchApi do end end + @doc false @spec build_url(String.t(), String.t()) :: String.t() defp build_url(ip, path), do: "https://" <> ip <> path + @doc false @spec get_allowed_data(String.t(), Credential.t(), String.t()) :: {:ok, map()} | {:error, String.t()} defp get_allowed_data(ip, credential, type) when type in @allowed_types do payload = build_payload(credential, %{"type" => type}) make_request(ip, "/getalloweddata", payload) end + @doc false @spec get_search_logs(String.t(), Credential.t(), map()) :: {:ok, map()} | {:error, String.t()} defp get_search_logs(ip, credential, request_data) do payload = build_payload(credential, %{"requestData" => Jason.encode!(request_data)}) make_request(ip, "/getsearchlogs", payload) end + @doc false @spec build_payload(Credential.t(), map()) :: String.t() defp build_payload(%Credential{} = credential, data) do Map.merge(