diff --git a/lib/plausible/plugins/api/context/shared_links.ex b/lib/plausible/plugins/api/context/shared_links.ex new file mode 100644 index 000000000..0fc1f7334 --- /dev/null +++ b/lib/plausible/plugins/api/context/shared_links.ex @@ -0,0 +1,54 @@ +defmodule Plausible.Plugins.API.Context.SharedLinks do + @moduledoc """ + Plugins API Context module for Shared Links. + All high level Shared Links operations should be implemented here. + """ + import Ecto.Query + import Plausible.Plugins.API.Pagination + + alias Plausible.Repo + + @spec get_shared_links(Plausible.Site.t(), map()) :: {:ok, Paginator.Page.t()} + def get_shared_links(site, params) do + query = + from l in Plausible.Site.SharedLink, + where: l.site_id == ^site.id, + order_by: [desc: l.id] + + {:ok, paginate(query, params, cursor_fields: [{:id, :desc}])} + end + + @spec get(Plausible.Site.t(), pos_integer() | String.t()) :: nil | Plausible.Site.SharedLink.t() + def get(site, id) when is_integer(id) do + get_by_id(site, id) + end + + def get(site, name) when is_binary(name) do + get_by_name(site, name) + end + + @spec get_or_create(Plausible.Site.t(), String.t(), String.t() | nil) :: + {:ok, Plausible.Site.SharedLink.t()} + def get_or_create(site, name, password \\ nil) do + case get_by_name(site, name) do + nil -> Plausible.Sites.create_shared_link(site, name, password) + shared_link -> {:ok, shared_link} + end + end + + defp get_by_id(site, id) do + Repo.one( + from l in Plausible.Site.SharedLink, + where: l.site_id == ^site.id, + where: l.id == ^id + ) + end + + defp get_by_name(site, name) do + Repo.one( + from l in Plausible.Site.SharedLink, + where: l.site_id == ^site.id, + where: l.name == ^name + ) + end +end diff --git a/lib/plausible/plugins/api/pagination.ex b/lib/plausible/plugins/api/pagination.ex new file mode 100644 index 000000000..e5398ac81 --- /dev/null +++ b/lib/plausible/plugins/api/pagination.ex @@ -0,0 +1,43 @@ +defmodule Plausible.Plugins.API.Pagination do + @moduledoc """ + Cursor-based pagination for the Plugins API. + Can be moved to another namespace in case used elsewhere. + """ + + @limit 10 + @maximum_limit 100 + + @spec paginate(Ecto.Queryable.t(), map(), Keyword.t(), Keyword.t()) :: Paginator.Page.t() + def paginate(queryable, params, opts, repo_opts \\ []) do + opts = Keyword.merge([limit: @limit, maximum_limit: @maximum_limit], opts) + + Paginator.paginate( + queryable, + Keyword.merge(opts, to_pagination_opts(params)), + Plausible.Repo, + repo_opts + ) + end + + defp to_pagination_opts(params) do + Enum.reduce(params, Keyword.new(), fn + {"after", cursor}, acc -> + Keyword.put(acc, :after, cursor) + + {"before", cursor}, acc -> + Keyword.put(acc, :before, cursor) + + {"limit", limit}, acc -> + limit = to_int(limit) + + if limit > 0 and limit <= @maximum_limit do + Keyword.put(acc, :limit, limit) + else + acc + end + end) + end + + defp to_int(x) when is_binary(x), do: String.to_integer(x) + defp to_int(x) when is_integer(x), do: x +end diff --git a/lib/plausible/plugins/api/tokens.ex b/lib/plausible/plugins/api/tokens.ex index cd3cff962..821ef3687 100644 --- a/lib/plausible/plugins/api/tokens.ex +++ b/lib/plausible/plugins/api/tokens.ex @@ -10,10 +10,9 @@ defmodule Plausible.Plugins.API.Tokens do import Ecto.Query @spec create(Site.t(), String.t()) :: - {:ok, Token.t(), String.t()} | {:error, Ecto.Changeset.t()} - def create(%Site{} = site, description) do - with generated_token <- Token.generate(), - changeset <- Token.insert_changeset(site, generated_token, %{description: description}), + {:ok, Token.t(), String.t(), String.t()} | {:error, Ecto.Changeset.t()} + def create(%Site{} = site, description, generated_token \\ Token.generate()) do + with changeset <- Token.insert_changeset(site, generated_token, %{description: description}), {:ok, saved_token} <- Repo.insert(changeset) do {:ok, saved_token, generated_token.raw} end diff --git a/lib/plausible/site/shared_link.ex b/lib/plausible/site/shared_link.ex index e01c582f8..eb6afaf71 100644 --- a/lib/plausible/site/shared_link.ex +++ b/lib/plausible/site/shared_link.ex @@ -2,6 +2,8 @@ defmodule Plausible.Site.SharedLink do use Ecto.Schema import Ecto.Changeset + @type t() :: %__MODULE__{} + schema "shared_links" do belongs_to :site, Plausible.Site field :name, :string diff --git a/lib/plausible_web.ex b/lib/plausible_web.ex index 4af57885a..4c6f9d8dc 100644 --- a/lib/plausible_web.ex +++ b/lib/plausible_web.ex @@ -43,6 +43,42 @@ defmodule PlausibleWeb do end end + def plugins_api_controller do + quote do + use Phoenix.Controller, namespace: PlausibleWeb.Plugins.API + import Plug.Conn + import PlausibleWeb.Plugins.API.Router.Helpers + import PlausibleWeb.Plugins.API, only: [base_uri: 0] + + alias PlausibleWeb.Plugins.API.Schemas + alias PlausibleWeb.Plugins.API.Views + alias Plausible.Plugins.API.Context + + plug(OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true, replace_params: false) + + use OpenApiSpex.ControllerSpecs + end + end + + def plugins_api_view do + quote do + use Phoenix.View, + namespace: PlausibleWeb.Plugins.API, + root: "" + + alias PlausibleWeb.Plugins.API.Router.Helpers + import PlausibleWeb.Plugins.API.Views.Pagination, only: [render_metadata_links: 4] + end + end + + def open_api_schema do + quote do + require OpenApiSpex + alias OpenApiSpex.Schema + alias PlausibleWeb.Plugins.API.Schemas + end + end + @doc """ When used, dispatch to the appropriate controller/view/etc. """ diff --git a/lib/plausible_web/plugins/api.ex b/lib/plausible_web/plugins/api.ex new file mode 100644 index 000000000..aa3a9ce01 --- /dev/null +++ b/lib/plausible_web/plugins/api.ex @@ -0,0 +1,16 @@ +defmodule PlausibleWeb.Plugins.API do + @moduledoc """ + Plausible Plugins API + """ + + @doc """ + Returns the API base URI, so that complete URLs can + be generated from forwared Router helpers. + """ + @spec base_uri() :: URI.t() + def base_uri() do + PlausibleWeb.Endpoint.url() + |> Path.join("/api/plugins") + |> URI.new!() + end +end diff --git a/lib/plausible_web/plugins/api/controllers/shared_links.ex b/lib/plausible_web/plugins/api/controllers/shared_links.ex new file mode 100644 index 000000000..a344b7e38 --- /dev/null +++ b/lib/plausible_web/plugins/api/controllers/shared_links.ex @@ -0,0 +1,109 @@ +defmodule PlausibleWeb.Plugins.API.Controllers.SharedLinks do + @moduledoc """ + Controller for the Shared Link resource under Plugins API + """ + use PlausibleWeb, :plugins_api_controller + + operation(:index, + summary: "Retrieve Shared Links", + parameters: [ + limit: [in: :query, type: :integer, description: "Maximum entries per page", example: 10], + after: [ + in: :query, + type: :string, + description: "Cursor value to seek after - generated internally" + ], + before: [ + in: :query, + type: :string, + description: "Cursor value to seek before - generated internally" + ] + ], + responses: %{ + ok: {"Shared Links response", "application/json", Schemas.SharedLink.ListResponse}, + unauthorized: {"Unauthorized", "application/json", Schemas.Unauthorized} + } + ) + + @spec index(Plug.Conn.t(), %{}) :: Plug.Conn.t() + def index(conn, _params) do + {:ok, pagination} = + Context.SharedLinks.get_shared_links(conn.assigns.authorized_site, conn.query_params) + + conn + |> put_view(Views.SharedLink) + |> render("index.json", %{pagination: pagination}) + end + + operation(:create, + summary: "Create Shared Link", + request_body: {"Shared Link params", "application/json", Schemas.SharedLink.CreateRequest}, + responses: %{ + created: {"Shared Link", "application/json", Schemas.SharedLink}, + unauthorized: {"Unauthorized", "application/json", Schemas.Unauthorized}, + unprocessable_entity: + {"Unprocessable entity", "application/json", Schemas.UnprocessableEntity} + } + ) + + @spec create(Plug.Conn.t(), map()) :: Plug.Conn.t() + def create( + %{ + private: %{ + open_api_spex: %{ + body_params: %Schemas.SharedLink.CreateRequest{name: name, password: password} + } + } + } = conn, + _params + ) do + site = conn.assigns.authorized_site + + {:ok, shared_link} = Context.SharedLinks.get_or_create(site, name, password) + + conn + |> put_view(Views.SharedLink) + |> put_status(:created) + |> put_resp_header("location", shared_links_url(base_uri(), :get, shared_link.id)) + |> render("shared_link.json", shared_link: shared_link, authorized_site: site) + end + + operation(:get, + summary: "Retrieve Shared Link by ID", + parameters: [ + id: [ + in: :path, + type: :integer, + description: "Shared Link ID", + example: 123, + required: true + ] + ], + responses: %{ + created: {"Shared Link", "application/json", Schemas.SharedLink}, + not_found: {"NotFound", "application/json", Schemas.NotFound}, + unauthorized: {"Unauthorized", "application/json", Schemas.Unauthorized}, + unprocessable_entity: + {"Unprocessable entity", "application/json", Schemas.UnprocessableEntity} + } + ) + + @spec get(Plug.Conn.t(), map()) :: Plug.Conn.t() + def get(%{private: %{open_api_spex: %{params: %{id: id}}}} = conn, _params) do + site = conn.assigns.authorized_site + + case Context.SharedLinks.get(site, id) do + nil -> + conn + |> put_view(Views.Error) + |> put_status(:not_found) + |> render("404.json") + + shared_link -> + conn + |> put_view(Views.SharedLink) + |> put_status(:ok) + |> render("shared_link.json", shared_link: shared_link, authorized_site: site) + end + end +end diff --git a/lib/plausible_web/plugins/api/router.ex b/lib/plausible_web/plugins/api/router.ex new file mode 100644 index 000000000..2ab4fdc0f --- /dev/null +++ b/lib/plausible_web/plugins/api/router.ex @@ -0,0 +1,26 @@ +defmodule PlausibleWeb.Plugins.API.Router do + use PlausibleWeb, :router + + pipeline :auth do + plug(PlausibleWeb.Plugs.AuthorizePluginsAPI) + end + + pipeline :api do + plug(:accepts, ["json"]) + plug(OpenApiSpex.Plug.PutApiSpec, module: PlausibleWeb.Plugins.API.Spec) + end + + scope "/spec" do + pipe_through(:api) + get("/openapi", OpenApiSpex.Plug.RenderSpec, []) + get("/swagger-ui", OpenApiSpex.Plug.SwaggerUI, path: "/api/plugins/spec/openapi") + end + + scope "/v1", PlausibleWeb.Plugins.API.Controllers do + pipe_through([:api, :auth]) + + get("/shared_links", SharedLinks, :index) + get("/shared_links/:id", SharedLinks, :get) + post("/shared_links", SharedLinks, :create) + end +end diff --git a/lib/plausible_web/plugins/api/schemas/error.ex b/lib/plausible_web/plugins/api/schemas/error.ex new file mode 100644 index 000000000..2285f1e8e --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/error.ex @@ -0,0 +1,16 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.Error do + @moduledoc """ + OpenAPI schema for an error included in a response + """ + + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + description: """ + An explanation of an error that occurred within the Plugins API + """, + type: :object, + required: [:detail], + properties: %{detail: %OpenApiSpex.Schema{type: :string}} + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/link.ex b/lib/plausible_web/plugins/api/schemas/link.ex new file mode 100644 index 000000000..676687ead --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/link.ex @@ -0,0 +1,13 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.Link do + @moduledoc """ + OpenAPI Link schema + """ + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + title: "Link", + type: :object, + required: [:url], + properties: %{url: %OpenApiSpex.Schema{type: :string}} + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/not_found.ex b/lib/plausible_web/plugins/api/schemas/not_found.ex new file mode 100644 index 000000000..7d0efd723 --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/not_found.ex @@ -0,0 +1,22 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.NotFound do + @moduledoc """ + OpenAPI schema for a generic 404 response + """ + + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + description: """ + The response that is returned when the user makes a request to a non-existing resource + """, + type: :object, + title: "NotFoundError", + required: [:errors], + properties: %{ + errors: %OpenApiSpex.Schema{ + items: Schemas.Error, + type: :array + } + } + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/pagination_metadata.ex b/lib/plausible_web/plugins/api/schemas/pagination_metadata.ex new file mode 100644 index 000000000..00a3651e7 --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/pagination_metadata.ex @@ -0,0 +1,25 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.PaginationMetadata do + @moduledoc """ + Pagination metadata OpenAPI schema + """ + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + title: "PaginationMetadata", + description: "Pagination meta data", + type: :object, + required: [:has_next_page, :has_prev_page], + properties: %{ + has_next_page: %OpenApiSpex.Schema{type: :boolean}, + has_prev_page: %OpenApiSpex.Schema{type: :boolean}, + links: %OpenApiSpex.Schema{ + items: Schemas.Link, + properties: %{ + next: %OpenApiSpex.Reference{"$ref": "#/components/schemas/Link"}, + prev: %OpenApiSpex.Reference{"$ref": "#/components/schemas/Link"} + }, + type: :object + } + } + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/shared_link.ex b/lib/plausible_web/plugins/api/schemas/shared_link.ex new file mode 100644 index 000000000..81ecff96f --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/shared_link.ex @@ -0,0 +1,27 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.SharedLink do + @moduledoc """ + OpenAPI schema for SharedLink object + """ + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + description: "Shared Link object", + type: :object, + required: [:data], + properties: %{ + data: %Schema{ + type: :object, + required: [:id, :name, :password_protected, :href], + properties: %{ + id: %Schema{type: :integer, description: "Shared Link ID"}, + name: %Schema{type: :string, description: "Shared Link Name"}, + password_protected: %Schema{ + type: :boolean, + description: "Shared Link Has Password" + }, + href: %Schema{type: :string, description: "Shared Link URL"} + } + } + } + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/shared_link/create_request.ex b/lib/plausible_web/plugins/api/schemas/shared_link/create_request.ex new file mode 100644 index 000000000..65e5754e1 --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/shared_link/create_request.ex @@ -0,0 +1,20 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.SharedLink.CreateRequest do + @moduledoc """ + OpenAPI schema for SharedLink creation request + """ + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + title: "SharedLink.CreateRequest", + description: "Shared Links creation params", + type: :object, + required: [:name], + properties: %{ + name: %Schema{description: "Shared Link Name", type: :string}, + password: %Schema{description: "Shared Link Password", type: :string} + }, + example: %{ + name: "My Shared Dashboard" + } + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/shared_link/list_response.ex b/lib/plausible_web/plugins/api/schemas/shared_link/list_response.ex new file mode 100644 index 000000000..66ebc70bb --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/shared_link/list_response.ex @@ -0,0 +1,29 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.SharedLink.ListResponse do + @moduledoc """ + OpenAPI schema for SharedLink list response + """ + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + title: "SharedLink.ListResponse", + description: "Shared Links list response", + type: :object, + required: [:data, :meta], + properties: %{ + data: %Schema{ + items: Schemas.SharedLink, + type: :array + }, + meta: %OpenApiSpex.Schema{ + required: [:pagination], + properties: %{ + pagination: %OpenApiSpex.Reference{ + "$ref": "#/components/schemas/PaginationMetadata" + } + }, + type: :object, + items: Schemas.PaginationMetadata + } + } + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/unauthorized.ex b/lib/plausible_web/plugins/api/schemas/unauthorized.ex new file mode 100644 index 000000000..ceaf6f724 --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/unauthorized.ex @@ -0,0 +1,22 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.Unauthorized do + @moduledoc """ + OpenAPI schema for a generic 401 response + """ + + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + description: """ + The response that is returned when the user makes an unauthorized request. + """, + type: :object, + title: "UnauthorizedError", + required: [:errors], + properties: %{ + errors: %OpenApiSpex.Schema{ + items: Schemas.Error, + type: :array + } + } + }) +end diff --git a/lib/plausible_web/plugins/api/schemas/unprocessable_entity.ex b/lib/plausible_web/plugins/api/schemas/unprocessable_entity.ex new file mode 100644 index 000000000..76c3db73f --- /dev/null +++ b/lib/plausible_web/plugins/api/schemas/unprocessable_entity.ex @@ -0,0 +1,23 @@ +defmodule PlausibleWeb.Plugins.API.Schemas.UnprocessableEntity do + @moduledoc """ + OpenAPI schema for a generic 422 response + """ + + use PlausibleWeb, :open_api_schema + + OpenApiSpex.schema(%{ + description: """ + The response that is returned when the user makes a request that cannot be + processed. + """, + type: :object, + title: "UnprocessableEntityError", + required: [:errors], + properties: %{ + errors: %OpenApiSpex.Schema{ + items: Schemas.Error, + type: :array + } + } + }) +end diff --git a/lib/plausible_web/plugins/api/spec.ex b/lib/plausible_web/plugins/api/spec.ex new file mode 100644 index 000000000..31e0ba5a2 --- /dev/null +++ b/lib/plausible_web/plugins/api/spec.ex @@ -0,0 +1,45 @@ +defmodule PlausibleWeb.Plugins.API.Spec do + @moduledoc """ + OpenAPI specification for the Plugins API + """ + alias OpenApiSpex.{Components, Info, OpenApi, Paths, Server} + alias PlausibleWeb.Plugins.API.Router + @behaviour OpenApi + + @impl OpenApi + def spec do + %OpenApi{ + servers: [ + %Server{ + description: "This server", + url: to_string(PlausibleWeb.Plugins.API.base_uri()), + variables: %{} + } + ], + info: %Info{ + title: "Plausible Plugins API", + version: "1.0-rc" + }, + # Populate the paths from a phoenix router + paths: Paths.from_router(Router), + components: %Components{ + securitySchemes: %{ + "basic_auth" => %OpenApiSpex.SecurityScheme{ + type: "http", + scheme: "basic", + description: """ + HTTP basic access authentication using your Site domain as the + username and the Plugins API Token contents as the password. + + For more information see + https://en.wikipedia.org/wiki/Basic_access_authentication + """ + } + } + }, + security: [%{"basic_auth" => []}] + } + # Discover request/response schemas from path specs + |> OpenApiSpex.resolve_schema_modules() + end +end diff --git a/lib/plausible_web/plugins/api/views/error.ex b/lib/plausible_web/plugins/api/views/error.ex new file mode 100644 index 000000000..7c7ec6014 --- /dev/null +++ b/lib/plausible_web/plugins/api/views/error.ex @@ -0,0 +1,23 @@ +defmodule PlausibleWeb.Plugins.API.Views.Error do + @moduledoc """ + View for rendering Plugins REST API errors + """ + use PlausibleWeb, :plugins_api_view + + def template_not_found(_template, assigns) do + render("500.json", assigns) + end + + @spec render(String.t(), map) :: map | binary() + def render("400.json", _assigns) do + %{errors: [%{detail: "Bad request"}]} + end + + def render("404.json", _assigns) do + %{errors: [%{detail: "Plugins API: resource not found"}]} + end + + def render("500.json", _assigns) do + %{errors: [%{detail: "Plugins API: Internal server error"}]} + end +end diff --git a/lib/plausible_web/plugins/api/views/pagination.ex b/lib/plausible_web/plugins/api/views/pagination.ex new file mode 100644 index 000000000..0b3f64522 --- /dev/null +++ b/lib/plausible_web/plugins/api/views/pagination.ex @@ -0,0 +1,66 @@ +defmodule PlausibleWeb.Plugins.API.Views.Pagination do + @moduledoc """ + A view capable of rendering pagination metadata included + in responses containing lists of objects. + """ + use Phoenix.View, + namespace: PlausibleWeb.Plugins.API, + root: "" + + alias PlausibleWeb.Plugins.API.Router.Helpers + + def render_metadata_links(meta, helper_fn, helper_fn_args, existing_params \\ %{}) do + render(__MODULE__, "pagination.json", %{ + meta: meta, + url_helper: fn query_params -> + existing_params = Map.drop(existing_params, ["before", "after"]) + + query_params = + query_params + |> Enum.into(%{}) + |> Map.merge(existing_params) + + args = [ + PlausibleWeb.Plugins.API.base_uri() + | List.wrap(helper_fn_args) ++ [query_params] + ] + + apply(Helpers, helper_fn, args) + end + }) + end + + @spec render(binary(), map()) :: + binary() + def render("pagination.json", %{meta: meta, url_helper: url_helper_fn}) do + pagination = + [ + {:after, :next, :has_next_page}, + {:before, :prev, :has_prev_page} + ] + |> Enum.reduce(%{}, fn + {meta_key, url_key, sibling_key}, acc -> + meta_value = Map.get(meta, meta_key) + + if meta_value do + url = url_helper_fn.([{meta_key, meta_value}]) + + acc + |> Map.update( + :links, + %{url_key => %{url: url}}, + &Map.put(&1, url_key, %{url: url}) + ) + |> Map.put(sibling_key, true) + else + acc + |> Map.update(:links, %{}, & &1) + |> Map.put(sibling_key, false) + end + end) + + %{ + pagination: pagination + } + end +end diff --git a/lib/plausible_web/plugins/api/views/shared_link.ex b/lib/plausible_web/plugins/api/views/shared_link.ex new file mode 100644 index 000000000..e3b5ed2a3 --- /dev/null +++ b/lib/plausible_web/plugins/api/views/shared_link.ex @@ -0,0 +1,32 @@ +defmodule PlausibleWeb.Plugins.API.Views.SharedLink do + @moduledoc """ + View for rendering Shared Links in the Plugins API + """ + + use PlausibleWeb, :plugins_api_view + + def render("index.json", %{ + pagination: %{entries: shared_links, metadata: metadata}, + authorized_site: site, + conn: conn + }) do + %{ + data: render_many(shared_links, __MODULE__, "shared_link.json", authorized_site: site), + meta: render_metadata_links(metadata, :shared_links_url, :index, conn.query_params) + } + end + + def render("shared_link.json", %{ + shared_link: shared_link, + authorized_site: site + }) do + %{ + data: %{ + id: shared_link.id, + name: shared_link.name, + password_protected: is_binary(shared_link.password_hash), + href: Plausible.Sites.shared_link_url(site, shared_link) + } + } + end +end diff --git a/lib/plausible_web/router.ex b/lib/plausible_web/router.ex index a64a02a3a..c32bf5104 100644 --- a/lib/plausible_web/router.ex +++ b/lib/plausible_web/router.ex @@ -67,6 +67,10 @@ defmodule PlausibleWeb.Router do forward "/", FunWithFlags.UI.Router, namespace: "flags" end + scope path: "/api/plugins" do + forward "/", PlausibleWeb.Plugins.API.Router + end + scope "/api/stats", PlausibleWeb.Api do pipe_through :internal_stats_api get "/:domain/funnels/:id", StatsController, :funnel diff --git a/lib/plausible_web/views/error_view.ex b/lib/plausible_web/views/error_view.ex index 1299731c1..1e133e6f5 100644 --- a/lib/plausible_web/views/error_view.ex +++ b/lib/plausible_web/views/error_view.ex @@ -1,6 +1,19 @@ defmodule PlausibleWeb.ErrorView do use PlausibleWeb, :view + def render("500.json", %{conn: %{private: %{PlausibleWeb.Plugins.API.Router => _}}}) do + contact_support_note = + if not Plausible.Release.selfhost?() do + "If the problem persists please contact support@plausible.io" + end + + %{ + errors: [ + %{detail: "Internal server error, please try again. #{contact_support_note}"} + ] + } + end + def render("500.json", _assigns) do %{ status: 500, diff --git a/mix.exs b/mix.exs index 76ec97cc7..d3b5e18a7 100644 --- a/mix.exs +++ b/mix.exs @@ -122,7 +122,9 @@ defmodule Plausible.MixProject do {:mjml_eex, "~> 0.9.0"}, {:mjml, "~> 1.5.0"}, {:heroicons, "~> 0.5.0"}, - {:zxcvbn, git: "https://github.com/techgaun/zxcvbn-elixir.git"} + {:zxcvbn, git: "https://github.com/techgaun/zxcvbn-elixir.git"}, + {:open_api_spex, "~> 3.18"}, + {:paginator, git: "https://github.com/duffelhq/paginator.git"} ] end diff --git a/mix.lock b/mix.lock index 37412fed4..a570617d6 100644 --- a/mix.lock +++ b/mix.lock @@ -92,6 +92,7 @@ "oban": {:hex, :oban, "2.12.1", "f604d7e6a8be9fda4a9b0f6cebbd633deba569f85dbff70c4d25d99a6f023177", [:mix], [{:ecto_sql, "~> 3.6", [hex: :ecto_sql, repo: "hexpm", optional: false]}, {:jason, "~> 1.1", [hex: :jason, repo: "hexpm", optional: false]}, {:postgrex, "~> 0.16", [hex: :postgrex, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "9b1844c2b74e0d788b73e5144b0c9d5674cb775eae29d88a36f3c3b48d42d058"}, "observer_cli": {:hex, :observer_cli, "1.7.3", "25d094d485f47239f218b53df0691a102fef13071dfd0d04922b5142297cfc93", [:mix, :rebar3], [{:recon, "~>2.5.1", [hex: :recon, repo: "hexpm", optional: false]}], "hexpm", "a41b6d3e11a3444e063e09cc225f7f3e631ce14019e5fbcaebfda89b1bd788ea"}, "octo_fetch": {:hex, :octo_fetch, "0.3.0", "89ff501d2ac0448556ff1931634a538fe6d6cd358ba827ce1747e6a42a46efbf", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}], "hexpm", "c07e44f2214ab153743b7b3182f380798d0b294b1f283811c1e30cff64096d3d"}, + "open_api_spex": {:hex, :open_api_spex, "3.18.0", "f9952b6bc8a1bf14168f3754981b7c8d72d015112bfedf2588471dd602e1e715", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:plug, "~> 1.7", [hex: :plug, repo: "hexpm", optional: false]}, {:poison, "~> 3.0 or ~> 4.0 or ~> 5.0", [hex: :poison, repo: "hexpm", optional: true]}, {:ymlr, "~> 2.0 or ~> 3.0 or ~> 4.0", [hex: :ymlr, repo: "hexpm", optional: true]}], "hexpm", "37849887ab67efab052376401fac28c0974b273ffaecd98f4532455ca0886464"}, "opentelemetry": {:hex, :opentelemetry, "1.1.1", "02de53d7dcafc087793ddf98cac946aaaa13c99cb6a7e568d9bb5ce4552b340e", [:rebar3], [{:opentelemetry_api, "~> 1.1", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}], "hexpm", "43a807d536bca55542731ddb5ecf68c0b3b433ff98713a6496058075bac70031"}, "opentelemetry_api": {:hex, :opentelemetry_api, "1.1.0", "156366bfbf249f54daf2626e087e29ad91201eab670993fd9ae1bd278d03a096", [:mix, :rebar3], [], "hexpm", "e0d0b49e21e5785da675c97104c385283cae84fcc0d8522932a5dcf55489ead1"}, "opentelemetry_ecto": {:hex, :opentelemetry_ecto, "1.0.0", "8463cc466429b3e125ae236a5cc32869ea38c88eb2f07722dd88e78ceca6963c", [:mix], [{:opentelemetry_api, "~> 1.0", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}, {:opentelemetry_process_propagator, "~> 0.1.0", [hex: :opentelemetry_process_propagator, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "39cc60dbdd54e371bd12fb010ee960de851d782dca197efefa5c35eb6b4c18bd"}, @@ -100,6 +101,7 @@ "opentelemetry_phoenix": {:hex, :opentelemetry_phoenix, "1.0.0", "73b8fee8bca6ac7a6aa0b17f61eb63494d1c78fffccdbac9656d92d279f9980c", [:mix], [{:opentelemetry_api, "~> 1.0", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}, {:opentelemetry_telemetry, "~> 1.0", [hex: :opentelemetry_telemetry, repo: "hexpm", optional: false]}, {:plug, ">= 1.11.0", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "9cb30018fda95657f5698130541988b68269de2c9a870051f845f7e2193e72c3"}, "opentelemetry_process_propagator": {:hex, :opentelemetry_process_propagator, "0.1.1", "81ec6825971903486ee73be23230d06764df39ee11011e520f601aa2bb21c893", [:mix, :rebar3], [{:opentelemetry_api, "~> 1.0", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}], "hexpm", "0572f26066bbb0457e22e169f966c0140a8f95237716c9c6ba4458d6dbaa724b"}, "opentelemetry_telemetry": {:hex, :opentelemetry_telemetry, "1.0.0", "d5982a319e725fcd2305b306b65c18a86afdcf7d96821473cf0649ff88877615", [:mix, :rebar3], [{:opentelemetry_api, "~> 1.0", [hex: :opentelemetry_api, repo: "hexpm", optional: false]}, {:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:telemetry_registry, "~> 0.3.0", [hex: :telemetry_registry, repo: "hexpm", optional: false]}], "hexpm", "3401d13a1d4b7aa941a77e6b3ec074f0ae77f83b5b2206766ce630123a9291a9"}, + "paginator": {:git, "https://github.com/duffelhq/paginator.git", "3508d6ad77a95ac1faf15d5fd7f959fab3e17da2", []}, "parallel_stream": {:hex, :parallel_stream, "1.1.0", "f52f73eb344bc22de335992377413138405796e0d0ad99d995d9977ac29f1ca9", [:mix], [], "hexpm", "684fd19191aedfaf387bbabbeb8ff3c752f0220c8112eb907d797f4592d6e871"}, "parse_trans": {:hex, :parse_trans, "3.4.1", "6e6aa8167cb44cc8f39441d05193be6e6f4e7c2946cb2759f015f8c56b76e5ff", [:rebar3], [], "hexpm", "620a406ce75dada827b82e453c19cf06776be266f5a67cff34e1ef2cbb60e49a"}, "phoenix": {:hex, :phoenix, "1.7.7", "4cc501d4d823015007ba3cdd9c41ecaaf2ffb619d6fb283199fa8ddba89191e0", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.6", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:websock_adapter, "~> 0.5.3", [hex: :websock_adapter, repo: "hexpm", optional: false]}], "hexpm", "8966e15c395e5e37591b6ed0bd2ae7f48e961f0f60ac4c733f9566b519453085"}, diff --git a/priv/repo/migrations/.formatter.exs b/priv/repo/migrations/.formatter.exs index 49f9151ed..99706d39e 100644 --- a/priv/repo/migrations/.formatter.exs +++ b/priv/repo/migrations/.formatter.exs @@ -1,4 +1,4 @@ [ - import_deps: [:ecto_sql], + import_deps: [:ecto_sql, :open_api_spex], inputs: ["*.exs"] ] diff --git a/priv/repo/migrations/20230918084301_fix_broken_goals.exs b/priv/repo/migrations/20230914071244_fix_broken_goals.exs similarity index 100% rename from priv/repo/migrations/20230918084301_fix_broken_goals.exs rename to priv/repo/migrations/20230914071244_fix_broken_goals.exs diff --git a/priv/repo/migrations/20230914071245_goals_unique.exs b/priv/repo/migrations/20230914071245_goals_unique.exs index 61e4abb06..3691ac6c7 100644 --- a/priv/repo/migrations/20230914071245_goals_unique.exs +++ b/priv/repo/migrations/20230914071245_goals_unique.exs @@ -18,8 +18,8 @@ defmodule Plausible.Repo.Migrations.GoalsUnique do GROUP BY (g2.site_id, CASE - WHEN g2.page_path IS NOT NULL THEN g2.page_path - WHEN g2.event_name IS NOT NULL THEN g2.event_name + WHEN g2.page_path IS NOT NULL THEN 'Page: ' || g2.page_path + WHEN g2.event_name IS NOT NULL THEN 'Event: ' || g2.event_name END ) ) AND g.id NOT IN ( diff --git a/priv/repo/seeds.exs b/priv/repo/seeds.exs index 98c6b8ea6..ed9d45b26 100644 --- a/priv/repo/seeds.exs +++ b/priv/repo/seeds.exs @@ -42,6 +42,12 @@ site = stats_start_date: NaiveDateTime.new!(imported_stats_range.first, ~T[00:00:00]) ) +# Plugins API: on dev environment, use "plausible-plugin-dev-seed-token" for "dummy.site" to authenticate +seeded_token = Plausible.Plugins.API.Token.generate("seed-token") + +{:ok, _, _} = + Plausible.Plugins.API.Tokens.create(site, "plausible-plugin-dev-seed-token", seeded_token) + {:ok, goal1} = Plausible.Goals.create(site, %{"page_path" => "/"}) {:ok, goal2} = Plausible.Goals.create(site, %{"page_path" => "/register"}) {:ok, goal3} = Plausible.Goals.create(site, %{"page_path" => "/login"}) diff --git a/test/plausible/plugins/api/pagination_test.exs b/test/plausible/plugins/api/pagination_test.exs new file mode 100644 index 000000000..ef233ca21 --- /dev/null +++ b/test/plausible/plugins/api/pagination_test.exs @@ -0,0 +1,64 @@ +defmodule Plausible.Plugins.API.PaginationTest do + use Plausible.DataCase, async: true + + alias Plausible.Plugins.API.Pagination + import Ecto.Query + + setup do + sites = insert_list(12, :site) + {:ok, %{sites: sites, query: from(s in Plausible.Site, order_by: [desc: :id])}} + end + + test "default page size", %{query: q} do + pagination = Pagination.paginate(q, %{}, cursor_fields: [id: :desc]) + + assert Enum.count(pagination.entries) == 10 + assert pagination.metadata.after + assert pagination.metadata.limit == 10 + refute pagination.metadata.before + end + + test "limit can be overriden", %{query: q} do + pagination = Pagination.paginate(q, %{"limit" => 3}, cursor_fields: [id: :desc]) + + assert Enum.count(pagination.entries) == 3 + assert pagination.metadata.limit == 3 + end + + test "limit exceeds all entries count", %{query: q, sites: sites} do + pagination = Pagination.paginate(q, %{"limit" => 100}, cursor_fields: [id: :desc]) + + assert Enum.count(pagination.entries) == Enum.count(sites) + end + + test "user provided limit exceeeds maximum limit", %{query: q} do + pagination = Pagination.paginate(q, %{"limit" => 200}, cursor_fields: [id: :desc]) + assert pagination.metadata.limit == 10 + end + + test "limit supplied as a string", %{query: q} do + pagination = Pagination.paginate(q, %{"limit" => "3"}, cursor_fields: [id: :desc]) + + assert Enum.count(pagination.entries) == 3 + assert pagination.metadata.limit == 3 + end + + test "next/prev page", %{query: q} do + page1 = Pagination.paginate(q, %{"limit" => 3}, cursor_fields: [id: :desc]) + + page_after = page1.metadata.after + + page2 = + Pagination.paginate(q, %{"limit" => 3, "after" => page_after}, cursor_fields: [id: :desc]) + + assert page1.entries != page2.entries + assert Enum.count(page1.entries) == Enum.count(page2.entries) + + page_before = page2.metadata.before + + assert ^page1 = + Pagination.paginate(q, %{"limit" => 3, "before" => page_before}, + cursor_fields: [id: :desc] + ) + end +end diff --git a/test/plausible_web/plugins/api/controllers/shared_links_test.exs b/test/plausible_web/plugins/api/controllers/shared_links_test.exs new file mode 100644 index 000000000..6e73365b4 --- /dev/null +++ b/test/plausible_web/plugins/api/controllers/shared_links_test.exs @@ -0,0 +1,238 @@ +defmodule PlausibleWeb.Plugins.API.Controllers.SharedLinksTest do + use PlausibleWeb.PluginsAPICase, async: true + + setup %{test: test} do + site = insert(:site) + {:ok, _token, raw_token} = Plausible.Plugins.API.Tokens.create(site, Atom.to_string(test)) + + {:ok, + %{ + site: site, + token: raw_token + }} + end + + describe "unathorized calls" do + for {method, url} <- [ + {:get, Routes.shared_links_url(base_uri(), :get, 1)}, + {:post, Routes.shared_links_url(base_uri(), :create)} + ] do + test "unauthorized call to #{url}", %{conn: conn} do + conn + |> unquote(method)(unquote(url)) + |> json_response(401) + |> assert_schema("UnauthorizedError", spec()) + end + end + end + + describe "get /shared_links/:id" do + test "validates input out of the box", %{conn: conn, token: token, site: site} do + url = Routes.shared_links_url(base_uri(), :get, "hello") + + resp = + conn + |> authenticate(site.domain, token) + |> get(url) + |> json_response(422) + |> assert_schema("UnprocessableEntityError", spec()) + + assert %{errors: [%{detail: "Invalid integer. Got: string"}]} = resp + end + + test "retrieve shared link by ID", %{conn: conn, site: site, token: token} do + shared_link = insert(:shared_link, name: "Some Link Name", site: site) + + url = Routes.shared_links_url(base_uri(), :get, shared_link.id) + + resp = + conn + |> authenticate(site.domain, token) + |> get(url) + |> json_response(200) + |> assert_schema("SharedLink", spec()) + + assert resp.data.href == + "http://localhost:8000/share/#{site.domain}?auth=#{shared_link.slug}" + + assert resp.data.id == shared_link.id + assert resp.data.password_protected == false + assert resp.data.name == "Some Link Name" + end + + test "fails to retrieve non-existing link", %{conn: conn, site: site, token: token} do + url = Routes.shared_links_url(base_uri(), :get, 666) + + conn + |> authenticate(site.domain, token) + |> get(url) + |> json_response(404) + |> assert_schema("NotFoundError", spec()) + end + + test "fails to retrieve link from another site", %{conn: conn, site: site, token: token} do + shared_link = insert(:shared_link, name: "Some Link Name", site: build(:site)) + url = Routes.shared_links_url(base_uri(), :get, shared_link.id) + + conn + |> authenticate(site.domain, token) + |> get(url) + |> json_response(404) + |> assert_schema("NotFoundError", spec()) + end + end + + describe "post /shared_links" do + test "successfully creates a shared link with the location header", %{ + conn: conn, + site: site, + token: token + } do + url = Routes.shared_links_url(base_uri(), :create) + + initial_conn = authenticate(conn, site.domain, token) + + conn = + initial_conn + |> put_req_header("content-type", "application/json") + |> post(url, %{ + name: "My Shared Link" + }) + + resp = + conn + |> json_response(201) + |> assert_schema("SharedLink", spec()) + + assert resp.data.name == "My Shared Link" + assert resp.data.href =~ "http://localhost:8000/share/#{site.domain}?auth=" + + [location] = get_resp_header(conn, "location") + + assert location == + Routes.shared_links_url(base_uri(), :get, resp.data.id) + + assert ^resp = + initial_conn + |> get(location) + |> json_response(200) + |> assert_schema("SharedLink", spec()) + end + + test "create is idempotent", %{ + conn: conn, + site: site, + token: token + } do + url = Routes.shared_links_url(base_uri(), :create) + + initial_conn = authenticate(conn, site.domain, token) + + create = fn -> + initial_conn + |> put_req_header("content-type", "application/json") + |> post(url, %{ + name: "My Shared Link" + }) + end + + conn = create.() + + resp = + conn + |> json_response(201) + |> assert_schema("SharedLink", spec()) + + id = resp.data.id + + conn = create.() + + assert ^id = + conn + |> json_response(201) + |> Map.fetch!("data") + |> Map.fetch!("id") + end + + test "validates input out of the box", %{conn: conn, token: token, site: site} do + url = Routes.shared_links_url(base_uri(), :create) + + resp = + conn + |> authenticate(site.domain, token) + |> put_req_header("content-type", "application/json") + |> post(url, %{}) + |> json_response(422) + |> assert_schema("UnprocessableEntityError", spec()) + + assert %{errors: [%{detail: "Missing field: name"}]} = resp + end + end + + describe "get /shared_links" do + test "returns an empty shared link list if there's none", %{ + conn: conn, + token: token, + site: site + } do + url = Routes.shared_links_url(base_uri(), :index) + + resp = + conn + |> authenticate(site.domain, token) + |> get(url) + |> json_response(200) + |> assert_schema("SharedLink.ListResponse", spec()) + + assert resp.data == [] + assert resp.meta.pagination.has_next_page == false + assert resp.meta.pagination.has_prev_page == false + assert resp.meta.pagination.links == %{} + end + + test "returns a shared links list with pagination", %{ + conn: conn, + token: token, + site: site + } do + for i <- 1..5 do + insert(:shared_link, site: site, name: "Shared Link #{i}") + end + + url = Routes.shared_links_url(base_uri(), :index, limit: 2) + + initial_conn = authenticate(conn, site.domain, token) + + page1 = + initial_conn + |> get(url) + |> json_response(200) + |> assert_schema("SharedLink.ListResponse", spec()) + + assert [%{data: %{name: "Shared Link 5"}}, %{data: %{name: "Shared Link 4"}}] = page1.data + assert page1.meta.pagination.has_next_page == true + assert page1.meta.pagination.has_prev_page == false + assert page1.meta.pagination.links.next + refute page1.meta.pagination.links[:prev] + + page2 = + initial_conn + |> get(page1.meta.pagination.links.next.url) + |> json_response(200) + |> assert_schema("SharedLink.ListResponse", spec()) + + assert [%{data: %{name: "Shared Link 3"}}, %{data: %{name: "Shared Link 2"}}] = page2.data + + assert page2.meta.pagination.has_next_page == true + assert page2.meta.pagination.has_prev_page == true + assert page2.meta.pagination.links.next + assert page2.meta.pagination.links.prev + + assert ^page1 = + initial_conn + |> get(page2.meta.pagination.links.prev.url) + |> json_response(200) + |> assert_schema("SharedLink.ListResponse", spec()) + end + end +end diff --git a/test/plausible_web/plugins/api/errors_test.exs b/test/plausible_web/plugins/api/errors_test.exs new file mode 100644 index 000000000..344b60708 --- /dev/null +++ b/test/plausible_web/plugins/api/errors_test.exs @@ -0,0 +1,41 @@ +defmodule PlausibleWeb.Plugins.API.ErrorsTest do + use ExUnit.Case, async: true + + import Phoenix.ConnTest, only: [json_response: 2] + + alias PlausibleWeb.Plugins.API.Errors + + describe "unauthorized/1" do + test "sends an 401 response with the `www-authenticate` header set" do + conn = + Plug.Test.conn(:get, "/") + |> Errors.unauthorized() + + assert conn.halted + + assert json_response(conn, 401) == %{ + "errors" => [%{"detail" => "Plugins API: unauthorized"}] + } + + assert Plug.Conn.get_resp_header(conn, "www-authenticate") == [ + ~s[Basic realm="Plugins API Access"] + ] + end + end + + describe "error/3" do + test "formats the given error message" do + message = "Some message" + + conn = + Plug.Test.conn(:get, "/") + |> Errors.error(:forbidden, message) + + assert conn.halted + + assert json_response(conn, 403) == %{ + "errors" => [%{"detail" => "Some message"}] + } + end + end +end diff --git a/test/support/plugins_api_case.ex b/test/support/plugins_api_case.ex new file mode 100644 index 000000000..21ce095fb --- /dev/null +++ b/test/support/plugins_api_case.ex @@ -0,0 +1,46 @@ +defmodule PlausibleWeb.PluginsAPICase do + @moduledoc """ + This module defines the test case to be used by + tests that require setting up a Plugins API connection. + """ + + use ExUnit.CaseTemplate + + using do + quote do + # The default endpoint for testing + @endpoint PlausibleWeb.Endpoint + + # Import conveniences for testing with connections + use Plausible.TestUtils + import Plug.Conn + import Phoenix.ConnTest + import PlausibleWeb.Plugins.API, only: [base_uri: 0] + import PlausibleWeb.Plugins.API.Spec, only: [spec: 0] + alias PlausibleWeb.Plugins.API.Router.Helpers, as: Routes + import Plausible.Factory + + import OpenApiSpex.TestAssertions + + def authenticate(conn, domain, raw_token) do + conn + |> Plug.Conn.put_req_header( + "authorization", + Plug.BasicAuth.encode_basic_auth(domain, raw_token) + ) + end + end + end + + setup tags do + :ok = Ecto.Adapters.SQL.Sandbox.checkout(Plausible.Repo) + + unless tags[:async] do + Ecto.Adapters.SQL.Sandbox.mode(Plausible.Repo, {:shared, self()}) + end + + conn = Phoenix.ConnTest.build_conn() + + {:ok, conn: conn} + end +end