Skip to content

Latest commit

 

History

History
85 lines (59 loc) · 3.83 KB

developing.md

File metadata and controls

85 lines (59 loc) · 3.83 KB
Raw

go-freeipa development guide

Generation process

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

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/schema.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.

Local hacks file

The schema.json file contains a lot of information.

Sometimes, the information it contains is ... inaccurate and requires local interpretation to really match the reality of the FreeIPA server response.

There is already a lot of required HACK in the gen/main.go file. Addind more would increase the complexity of the code and makes it even harder to maintain.

This is why a file was created to express some of those required but dirty hacks. The file is named dirty_overrides.json and currently contains very little data.

The data in this file is built with a try and error logic when a FreeIPA response breaks the generated.go code expectations.

This file is not supposed to be maintained over time and should be dropped as soon as a better solution is found.

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.