metosin / metosin/compojure-api

Immutable `restructure` interface

Open
#468 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Clojure
Stars
1.1k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

Instead of a big `restructure` multimethod that you need to manage extensions for, perhaps we can encourage more mix-and-match approaches that start to look like the kind of centralized config you'd expect from reitit.

One of the motivations is having full control and certainty over the restructure options for security purposes.

Since compojure-api is macro-based, the main obstacle here is forwarding the immutable config to the macros. This can be accomplished by a macro-generating macro.

e.g.,
```clojure
(ns my-bare-bones-compojure-api
"A version of compojure-api that only supports :tags."
(:require [compojure.api.immutable :as im]
[compojure.api.meta.tags]
[clojure.set :as set]))

(def ^:private options
{:restructure {:tags compojure.api.meta.tags/extension}})

(im/create-compojure-api `options)
=>
(defmacro create-compojure-api [options]
(assert (and (seq? options)
(= 2 (count options))
(= 'quote (first options))
(qualified-symbol? (second options)))
"Options must be a quoted qualified symbol whose var contains your configuration, like: (load-api `options)")
`(let [options# ~options]
(defmacro ~'GET {:style/indent 2 :arglists '([& ~'args])} [& args#] (GET options# args#))
(defmacro ~'ANY {:style/indent 2 :arglists '([& ~'args])} [& args#] (ANY options# args#))
(defmacro ~'PATCH {:style/indent 2 :arglists '([& ~'args])} [& args#] (PATCH options# args#))
(defmacro ~'DELETE {:style/indent 2 :arglists '([& ~'args])} [& args#] (DELETE options# args#))
(defmacro ~'POST {:style/indent 2 :arglists '([& ~'args])} [& args#] (POST options# args#))
(defmacro ~'PUT {:style/indent 2 :arglists '([& ~'args])} [& args#] (PUT options# args#))
(defmacro ~'context
"Like compojure.api.core/context, except the binding vector must be empty and
no binding-style options are allowed. This is to prevent the passed routes
from being reinitialized on every request."
{:style/indent 2 :arglists '~'([path arg & args])}
[path# arg# & args#]
(context options# path# arg# args#))
(defn ~'routes
"Create a Ring handler by combining several handlers into one."
{:style/indent 2 :arglists '~'([& handlers])}
[& handlers#]
(routes options# handlers#))
(defmacro ~'middleware
"Wraps routes with given middlewares using thread-first macro.
Note that middlewares will be executed even if routes in body
do not match the request uri. Be careful with middlewares that
have side-effects."
{:style/indent 1 :arglists '~'([middleware & body-exprs])}
[middleware# & body-exprs#]
(middleware options# middleware# body-exprs#))
(defmacro ~'undocumented
"Routes without route-documentation. Can be used to wrap routes,
not satisfying compojure.api.routes/Routing -protocol."
{:arglists '~'([& handlers])}
[& handlers#]
(undocumented options# handlers#))))
```

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the proposed create-compojure-api macro and its generated GET, ANY, PATCH, DELETE, POST, PUT, context, routes, middleware, and undocumented entry points. Review how the immutable options map is forwarded to these macros and how restructure extensions are selected. Done means an immutable, restricted configuration can generate the intended API without relying on the large extensible restructure multimethod.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.