defprotocol Paddle.Class do
@moduledoc ~S"""
Protocol used to allow some objects (mainly structs) to represent an LDAP
entry.
Implementing this protocol for your specific classes will enable you to
manipulate LDAP entries in an easier way than using DNs (hopefully).
If the class you want to implement is simple enough, you might want to use
the `Paddle.Class.Helper.gen_class_from_schema/3` or
`Paddle.Class.Helper.gen_class/2` macros.
For now, only two "classes" implementing this protocol are provided:
`Paddle.PosixAccount` and `Paddle.PosixGroup`.
"""
@spec unique_identifier(Paddle.Class.t()) :: atom
@doc ~S"""
Return the name of the attribute used in the DN to uniquely identify entries.
For example, the identifier for an account would be `:uid` because an account
DN would be like: `"uid=testuser,ou=People,..."`
"""
def unique_identifier(_)
@spec object_classes(Paddle.Class.t()) :: binary | [binary]
@doc ~S"""
Must return the class or the list of classes which this "object class"
belongs to.
For example, a posixAccount could have the following object classes:
`["account", "posixAccount"]`
The `"top"` class is not required.
"""
def object_classes(_)
@spec required_attributes(Paddle.Class.t()) :: [atom]
@doc ~S"""
Return the list of required attributes for this "class"
For example, for the posixAccount class, the following attributes are
required:
[:uid, :cn, :uidNumber, :gidNumber, :homeDirectory]
"""
def required_attributes(_)
@spec location(Paddle.Class.t()) :: binary | keyword
@doc ~S"""
Return the parent subDN (where to add / get entries of this type).
Example for users: `"ou=People"`
The top base (e.g. `"dc=organisation,dc=org"`) must not be specified.
"""
def location(_)
@spec generators(Paddle.Class.t()) :: [{atom, (Paddle.Class -> term)}]
@doc ~S"""
Return a list of attributes to be generated using the given functions.
**Warning:** do not use functions with side effects, as this function may be
called even if adding some LDAP entries fails.
Example: [uid: &Paddle.PosixAccount.get_next_uid/1]
This function must take 1 parameter which will be the current class object
(useful if you have interdependent attribute values) and must return the
generated value.
For example, with `%Paddle.PosixGroup{uid: "myUser", ...}` the function will
be called like this:
Paddle.PosixAccount.get_next_uid(%Paddle.PosixAccount{uid: "myUser", ...}
"""
def generators(_)
end
defmodule Paddle.Class.Helper do
@moduledoc ~S"""
A helper module to help generate paddle classes.
There is currently two ways of generating paddle classes:
## Using schema files
The simplest way is to find `*.schema` files which contain definitions of
LDAP object classes. You can find them in the `/etc/(open)ldap/schema/`
directory if you have OpenLDAP installed. If not, you can find most of them
[here](https://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=tree;f=servers/slapd/schema;h=55325b541890a9210178920c78231d2e392b0e39;hb=HEAD).
Then, add the path of these files in the Paddle configuration using the
`:schema_files` key (see the [`Paddle`](Paddle.html#module-configuration)
module toplevel documentation). Finally just call the
`gen_class_from_schema/3` macro from anywhere outside of a module.
Example:
require Paddle.Class.Helper
Paddle.Class.Helper.gen_class_from_schema MyApp.Room, ["room"], "ou=Rooms"
For a description of the parameters and more configuration options, see the
`gen_class_from_schema/3` macro documentation.
## Manually describing the class
If you're feeling more adventurous you can still use this helper you can also
specify by hand each part of the class using the
`Paddle.Class.Helper.gen_class/2` macro (if that still doesn't satisfy you,
you can always look at the `Paddle.Class` protocol).
Example (which is equivalent to the example above):
require Paddle.Class.Helper
Paddle.Class.Helper.gen_class MyApp.Room,
fields: [:commonName, :roomNumber, :description, :seeAlso, :telephoneNumber],
unique_identifier: :commonName,
object_classes: ["room"],
required_attributes: [:commonName],
location: "ou=Rooms"
The available options are all function names defined and documented
in the `Paddle.Class` protocol, plus the `:fields` option which
defines all the available fields for the given class.
Please note that using the `:generators` option here is discouraged
as generators should be inside the module and not elsewhere. Unless
you are sure what you are doing is elegant enough, you should define the
module yourself instead of using this macro with the `:generators` option
(see the `Paddle.Class` and the source of this macro for guidelines).
"""
@doc ~S"""
Generate a Paddle class.
Generate a Paddle class represented as a struct with the name `class_name`,
and the options `options` (see [the module toplevel
documentation](#module-manually-describing-the-class)).
"""
defmacro gen_class(class_name, options) do
fields = Keyword.get(options, :fields)
unique_identifier = Keyword.get(options, :unique_identifier)
object_classes = Keyword.get(options, :object_classes)
required_attributes = Keyword.get(options, :required_attributes)
location = Keyword.get(options, :location)
generators = Keyword.get(options, :generators, [])
quote do
defmodule unquote(class_name) do
defstruct unquote(fields)
end
defimpl Paddle.Class, for: unquote(class_name) do
def unique_identifier(_), do: unquote(unique_identifier)
def object_classes(_), do: unquote(object_classes)
def required_attributes(_), do: unquote(required_attributes)
def location(_), do: unquote(location)
def generators(_), do: unquote(generators)
end
end
end
@doc ~S"""
Generate a Paddle class from schema files.
Generate a Paddle class from one of the schema files passed as configuration
with the name `class_name`, with the given `object_classes` (can be a binary
or a list of binary), at the given location, optionally force specify
which field to use as a unique identifier (see
`Paddle.Class.unique_identifier/1`), and some optional generators (see
`Paddle.Class.generators/1`)
"""
defmacro gen_class_from_schema(
class_name,
object_classes,
location,
unique_identifier \\ nil,
generators \\ []
) do
{class_name, _bindings} = Code.eval_quoted(class_name, [], __CALLER__)
{object_classes, _bindings} = Code.eval_quoted(object_classes, [], __CALLER__)
{location, _bindings} = Code.eval_quoted(location, [], __CALLER__)
{unique_identifier, _bindings} = Code.eval_quoted(unique_identifier, [], __CALLER__)
{generators, _bindings} = Code.eval_quoted(generators, [], __CALLER__)
fields = Paddle.SchemaParser.attributes(object_classes)
required_attributes = Paddle.SchemaParser.required_attributes(object_classes)
unique_identifier = unique_identifier || hd(required_attributes)
quote do
defmodule unquote(class_name) do
defstruct unquote(fields)
end
defimpl Paddle.Class, for: unquote(class_name) do
def unique_identifier(_), do: unquote(unique_identifier)
def object_classes(_), do: unquote(object_classes)
def required_attributes(_), do: unquote(required_attributes)
def location(_), do: unquote(location)
def generators(_), do: unquote(generators)
end
end
end
end
