go-freeipa development guide

Generation process

ipalib source -----------> errors.json -\
            (./dump-errors)             |------> generated.go
                                        |(./gen)
FreeIPA instance --------> schema.json -/
             ("schema" call)

The above diagram shows the different steps to create the generated code. The results of each of these steps (errors.json, schema.json and generated.go) are all committed, so these steps do not have to be run by users of the library. This document explains what each step does and how to execute it.

Fetch the latest FreeIPA schema

FreeIPA exposes two API methods for getting a description of the API.

There is the json_metadata method, which is used by the official web UI to show the "API browser". The data returned by this method is not useful, since it does not describe any method responses (only requests).

There is also a schema method, which is called by the official CLI on first start. This has a slightly different structure, but notably also describes method respones. This is the method used to generate this library.

To regenerate data/schema.json: Frist, start a FreeIPA server (for example with Docker). Then, log in to the web UI in your browser and copy your ipa_session cookie. Finally, make a request like the following curl command does:

1. On your ipa server:

$ ipa --server
VERSION: 4.10.1, API_VERSION: 2.251

2. On your dev machine

Replace the {"method":"schema","params":[[],{"version":"2.251"} with the version shown in API_VERSION

curl 'https://your.ipaserver.com/ipa/session/json' -H 'Origin: https://your.ipaserver.com' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Cookie: ipa_session=3057327ac9ea5622d7011b122d47790e' -H 'Referer: https://your.ipaserver.com/ipa/ui/' --data-binary '{"method":"schema","params":[[],{"version":"2.280"}]}' --insecure > ./data/schema.json

You'll need to adjust the URLs and the value of the ipa_session cookie. You

Get the latest FreeIPA errors

The schema call does not return any information about possible error codes (eg. 4001 NotFound). This is generated by ./dump-errors/dump.py and saved to ./data/errors.json. This script requires Python 3, but has no other dependencies. It downloads ipalib/errors.py from a fixed commit on GitHub, imports it and extracts error codes from the classes which define them. You will probably want to adjust ERRORS_PY_URL to point to a newer commit.

Generate the code with the latest changes

You will need go for this step.

cd freeipa-go-client/gen
go run .

If you have any import errors, try this:

go mod tidy

Common tasks

Adjusting generated code

To adjust the generated code, without changing the targeted FreeIPA version, you only need to perform the ./gen step.

You would need this if you use only certains generated functions, which are not correctly generated, need to manually fix the issue

Targeting a newer FreeIPA version

To change the targeted FreeIPA version, you need to first need to perform the ./dump-errors step and the schema call. Afterwards, you need to perform the ./gen step.