feat(jwt): [#4191] extend Token.encode() to support custom headers

[s-aleshin]

Description

Allows passing custom JWT headers (e.g., kid) to Token.encode(). This improves flexibility in cases where custom JWT headers (like kid) are required.

Closes

Fixes #4191

[provinzkraut]

Two things:

1. This is a breaking change (for users that subclass Token), so it would have to be targeted at the v3 branch
2. I don't think we should add json_encoder and sort_headers, as they are specific to pyjwt, and this is meant as an abstraction over pyjwt, not a drop-in replacement. If you do need to customise how decode interacts with pyjwt, you can simply subclass Token

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.30%. Comparing base (61e9c18) to head (4692923).
Report is 1 commits behind head on v3.0.

Additional details and impacted files

@@            Coverage Diff             @@
##             v3.0    #4192      +/-   ##
==========================================
- Coverage   98.30%   98.30%   -0.01%     
==========================================
  Files         343      343              
  Lines       15815    15810       -5     
  Branches     1744     1743       -1     
==========================================
- Hits        15547    15542       -5     
  Misses        130      130              
  Partials      138      138              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[s-aleshin]

Two things:

1. This is a breaking change (for users that subclass Token), so it would have to be targeted at the v3 branch
2. I don't think we should add json_encoder and sort_headers, as they are specific to pyjwt, and this is meant as an abstraction over pyjwt, not a drop-in replacement. If you do need to customise how decode interacts with pyjwt, you can simply subclass Token

1. I’ve rebased the branch onto v3.0 as you suggested — the PR now targets the correct base.
2. Ok, I agree. json_encoder and sort_headers are specific for pyjwt and use rarely. Deleted from the PR.

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/4192

[provinzkraut]

Thanks @s-aleshin!