Skip to content

Latest commit

 

History

History
68 lines (49 loc) · 2.86 KB

developing.md

File metadata and controls

68 lines (49 loc) · 2.86 KB
Raw

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.

./gen step

gen is a golang package which uses text/template to create freeipa/generated.go using both .json files. It should be run from the ./gen directory.

schema call

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:

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

You'll need to adjust the URLs and the value of the ipa_session cookie. You may alse need to adjust version in the request body.

./dump-errors step

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.

Common tasks

Adjusting generated code

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

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.