feat: support custom headers

[alexanderzobnin]

Description

What problem is being solved?

Solves #669

How is it being solved?

Provide new --custom-headers flag which allows to pass custom user-defined headers which are then included to every request to API.

What changes are made to solve it?

Implemented new --custom-headers option by utilizing existing DefaultHeaders client config field.

References

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features
  • Added support for custom HTTP headers via the --custom-headers CLI flag. This repeatable flag accepts header values in name:value format, enabling users to include custom headers in requests.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7ae638dd-1f8f-432f-bef8-75575d58dfb9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

A new CLI flag --custom-headers is added to collect custom HTTP headers as a repeatable string array argument. This value is read during configuration initialization and passed to the OpenFGA SDK client via a new CustomHeaders field, with header parsing logic to extract name-value pairs from the provided strings.

Changes

Cohort / File(s)	Summary
CLI Input Collection cmd/root.go, internal/cmdutils/get-client-config.go	Added persistent --custom-headers flag definition and integrated flag value reading into client configuration initialization.
SDK Client Configuration internal/fga/fga.go	Added CustomHeaders field to ClientConfig struct and implemented header parsing logic (getCustomHeaders()) to convert string entries into a map format for SDK DefaultHeaders configuration.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: support custom headers' directly and clearly describes the main change in the pull request - adding support for custom HTTP headers via a new CLI flag.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR adds a CLI-level mechanism for supplying user-defined HTTP headers that are automatically included on all OpenFGA API requests, addressing #669 for deployments that require non-standard auth headers.

Changes:

• Introduces a new --custom-headers persistent flag and wires it into ClientConfig.
• Parses provided header strings into a map[string]string and passes them via the SDK DefaultHeaders configuration.
• Extends the serialized client config model to include custom_headers.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
internal/fga/fga.go	Adds CustomHeaders to config and applies parsed headers through the SDK client configuration.
internal/cmdutils/get-client-config.go	Reads the new custom-headers flag into fga.ClientConfig.
cmd/root.go	Registers the new persistent --custom-headers flag.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

cmd/root.go (1)

71-71: Clarify --custom-headers value format in help text.

Consider documenting the expected format (for example, Header-Name:Header Value) directly in the flag description to reduce invalid input.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cmd/root.go` at line 71, Update the flag description for
rootCmd.PersistentFlags().StringArray("custom-headers", ...) to clarify the
expected input format and reduce invalid values by documenting an example like
"Header-Name: Header Value" and specifying that the colon separates name and
value and the flag can be repeated for multiple headers; modify only the
description string passed to StringArray for the "custom-headers" flag to
include this format guidance and an example.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/fga/fga.go`:
- Around line 104-113: The getCustomHeaders method currently adds headers even
when the parsed header name is empty (e.g., ":value"); update
ClientConfig.getCustomHeaders to ignore entries with empty header names by
trimming parts[0] and checking head != "" before assigning headers[head] =
value, keeping the rest of the parsing logic the same so only valid non-empty
header keys are included.

---

Nitpick comments:
In `@cmd/root.go`:
- Line 71: Update the flag description for
rootCmd.PersistentFlags().StringArray("custom-headers", ...) to clarify the
expected input format and reduce invalid values by documenting an example like
"Header-Name: Header Value" and specifying that the colon separates name and
value and the flag can be repeated for multiple headers; modify only the
description string passed to StringArray for the "custom-headers" flag to
include this format guidance and an example.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 605667f4-98bb-4e92-9330-aac2d46d26b7

📥 Commits

Reviewing files that changed from the base of the PR and between add64f4 and f5174c7.

📒 Files selected for processing (3)

• cmd/root.go
• internal/cmdutils/get-client-config.go
• internal/fga/fga.go

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rhamzeh]

One more thing - can we add some tests for these, just to make sure all is good? And please make sure to run make lint and make format 🙏🏽

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[emilic]

Just a general comment, i happened to look at this and noticed that for env variables we have a bug in:

func BindViperToFlags(cmd *cobra.Command, viperInstance *viper.Viper) {
	cmd.Flags().VisitAll(func(flag *pflag.Flag) {
		configName := flag.Name

		if !flag.Changed && viperInstance.IsSet(configName) {
			value := viperInstance.Get(configName)
			err := cmd.Flags().Set(flag.Name, fmt.Sprintf("%v", value)) <---- Here
			cobra.CheckErr(err)
		}
	})

	for _, subcmd := range cmd.Commands() {
		BindViperToFlags(subcmd, viperInstance)
	}
}

If the custom headers is passed as an env variable it will stringify the the string array. It will probably work with one entry.

not sure how likely env vars are in your use case but i assume it would be for some auth headers and maybe not multiple.

this is not a problem with your PR but its a bug that came to light because of it. @rhamzeh - ill create a separate issue for this.

UPDATE: and i just noticed that co-pilot already flagged this.

[rhamzeh]

Thanks @alexanderzobnin - we'll fix the lint issue and merge :)

@emilic please do!

[rhamzeh]

@alexanderzobnin can I ask you to either:

• allow write access to your branch to maintainers so we can fix the lint issues (See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
• or fix the lint issues and push them on your end?

These are the changes needed:

• Lint (instead of applying, just run make lint on your end): 0001-chore-fix-lint.patch
• Fixes the security failure: 0002-chore-bump-toolchain-to-1.26.2.patch

[senojj]

???

[alexanderzobnin]

This is what @rhamzeh asked to do (this was a part of go toolchain bump).

[alexanderzobnin]

@rhamzeh should we keep it?

[senojj]

@rhamzeh was the addition of this file the intent? I wasn't sure if we were actually using the tool in the project.