option

Documentation

Overview

Package option holds the functional options for the fal client and the resolved CallOptions struct the feature packages consume. The per-method option interfaces keep an unexported apply method, so they remain sealed to this package (callers cannot invent their own option types) — the facade and feature packages dispatch options through the exported Resolve* functions instead.

The fal package re-exports every WithX/OnX constructor (fal.WithPath, ...), so callers normally do not import this package directly.

Index

• Constants
• func OnEnqueue(fn func(requestID string)) onEnqueueOption
• func OnQueueUpdate(fn func(status.Status)) onQueueUpdateOption
• func RequestHeaders(o *CallOptions) (map[string]string, error)
• func WithClientTimeout(d time.Duration) clientTimeoutOption
• func WithDecodeMessage(fn func([]byte) (any, error)) decodeMessageOption
• func WithEncodeMessage(fn func(any) ([]byte, error)) encodeMessageOption
• func WithFallbackRepository(repos ...string) fallbackRepoOption
• func WithHeaders(headers map[string]string) headersOption
• func WithHint(hint string) hintOption
• func WithInterval(d time.Duration) intervalOption
• func WithJWT(enabled bool) jwtOption
• func WithLifecycle(s *storage.Settings) lifecycleOption
• func WithLogs(enabled bool) logsOption
• func WithMaxBuffering(n int) maxBufferingOption
• func WithPath(path string) pathOption
• func WithPriority(priority string) priorityOption
• func WithRepository(repo string) repositoryOption
• func WithStartTimeout(d time.Duration) startTimeoutOption
• func WithTimeout(d time.Duration) timeoutOption
• func WithTokenExpiration(seconds int) tokenExpirationOption
• func WithWebhookURL(url string) webhookOption
• type CallOptions
  • func ResolveRealtime(opts ...RealtimeOption) *CallOptions
  • func ResolveRun(opts ...RunOption) *CallOptions
  • func ResolveStream(opts ...StreamOption) *CallOptions
  • func ResolveSubmit(opts ...SubmitOption) *CallOptions
  • func ResolveSubscribe(opts ...SubscribeOption) *CallOptions
  • func ResolveUpload(opts ...UploadOption) *CallOptions
• type RealtimeOption
• type RunOption
• type StreamOption
• type SubmitOption
• type SubscribeOption
• type UploadOption

Constants

const (
	PriorityNormal = "normal"
	PriorityLow    = "low"
)

Queue priority values for WithPriority.

const DefaultPollInterval = 100 * time.Millisecond

DefaultPollInterval is the queue poll interval used by Subscribe when none is given. It mirrors DEFAULT_QUEUE_POLL_INTERVAL in the Python client.

const DefaultRealtimeTokenExpiration = 120

DefaultRealtimeTokenExpiration mirrors REALTIME_TOKEN_EXPIRATION_SECONDS.

Functions

func OnEnqueue

func OnEnqueue(fn func(requestID string)) onEnqueueOption

OnEnqueue registers a callback invoked once with the request id after submission.

func OnQueueUpdate

func OnQueueUpdate(fn func(status.Status)) onQueueUpdateOption

OnQueueUpdate registers a callback invoked on every status poll during Subscribe.

func RequestHeaders

func RequestHeaders(o *CallOptions) (map[string]string, error)

RequestHeaders assembles the optional per-request headers shared by run, submit and subscribe, validating the start-timeout and priority values.

func WithClientTimeout

func WithClientTimeout(d time.Duration) clientTimeoutOption

WithClientTimeout bounds the total Subscribe operation; exceeding it cancels the request and returns a *TimeoutError.

func WithDecodeMessage

func WithDecodeMessage(fn func([]byte) (any, error)) decodeMessageOption

WithDecodeMessage overrides the realtime inbound message decoder (default msgpack).

func WithEncodeMessage

func WithEncodeMessage(fn func(any) ([]byte, error)) encodeMessageOption

WithEncodeMessage overrides the realtime outbound message encoder (default msgpack).

func WithFallbackRepository

func WithFallbackRepository(repos ...string) fallbackRepoOption

WithFallbackRepository sets the ordered fallback backends tried when the primary upload fails. Calling it with no arguments disables the default "fal" fallback. When this option is not used, the chain defaults to ["fal_v3", "fal"], matching the Python client.

func WithHeaders

func WithHeaders(headers map[string]string) headersOption

WithHeaders sets extra request headers. It takes ownership of the map and does not copy it, so do not mutate the map after passing it in. These headers are applied before the SDK-managed Authorization and User-Agent headers, which they cannot override.

func WithHint

func WithHint(hint string) hintOption

WithHint sets the X-Fal-Runner-Hint header.

func WithInterval

func WithInterval(d time.Duration) intervalOption

WithInterval sets the queue poll interval for Subscribe.

func WithJWT

func WithJWT(enabled bool) jwtOption

WithJWT toggles JWT-in-URL auth for realtime connections (default true).

Security note: with JWT enabled the token is placed in the WebSocket URL query string, which intermediaries may log. Prefer WithJWT(false) (Authorization header) for sensitive environments.

func WithLifecycle

func WithLifecycle(s *storage.Settings) lifecycleOption

WithLifecycle sets the storage lifecycle/ACL of the uploaded object.

func WithLogs

func WithLogs(enabled bool) logsOption

WithLogs requests logs in status updates during Subscribe.

func WithMaxBuffering

func WithMaxBuffering(n int) maxBufferingOption

WithMaxBuffering sets the server-side buffering window (1-60) for realtime.

func WithPath

func WithPath(path string) pathOption

WithPath sets the sub-path appended to the application endpoint.

func WithPriority

func WithPriority(priority string) priorityOption

WithPriority sets the X-Fal-Queue-Priority header. Use PriorityNormal or PriorityLow.

func WithRepository

func WithRepository(repo string) repositoryOption

WithRepository selects the primary upload backend ("fal_v3" or "fal").

func WithStartTimeout

func WithStartTimeout(d time.Duration) startTimeoutOption

WithStartTimeout sets the server-side queue wait limit (X-Fal-Request-Timeout).

func WithTimeout

func WithTimeout(d time.Duration) timeoutOption

WithTimeout sets the client-side HTTP timeout for a single call.

func WithTokenExpiration

func WithTokenExpiration(seconds int) tokenExpirationOption

WithTokenExpiration sets the realtime JWT expiration in seconds.

func WithWebhookURL

func WithWebhookURL(url string) webhookOption

WithWebhookURL registers a fal_webhook callback URL on Submit.

Types

type CallOptions

type CallOptions struct {
	Path          string
	Hint          string
	Logs          bool
	Interval      time.Duration
	Priority      string
	WebhookURL    string
	Headers       map[string]string
	StartTimeout  time.Duration
	ClientTimeout time.Duration
	Timeout       time.Duration
	OnEnqueue     func(string)
	OnQueueUpdate func(status.Status)

	// upload
	Repository         string
	FallbackRepository []string
	FallbackSet        bool // distinguishes an explicit (possibly empty) fallback from the default
	Lifecycle          *storage.Settings

	// realtime
	UseJWT          bool
	UseJWTSet       bool
	MaxBuffering    int
	TokenExpiration int
	EncodeMessage   func(any) ([]byte, error)
	DecodeMessage   func([]byte) (any, error)
}

CallOptions is the resolved, shared set of per-call settings every option writes into. Fields are exported so the feature packages can read them; callers configure them only through the WithX/OnX options and the Resolve* functions.

func ResolveRealtime

func ResolveRealtime(opts ...RealtimeOption) *CallOptions

ResolveRealtime applies opts onto a fresh CallOptions for the realtime methods.

func ResolveRun

func ResolveRun(opts ...RunOption) *CallOptions

ResolveRun applies opts onto a fresh CallOptions for Run.

func ResolveStream

func ResolveStream(opts ...StreamOption) *CallOptions

ResolveStream applies opts onto a fresh CallOptions for Stream.

func ResolveSubmit

func ResolveSubmit(opts ...SubmitOption) *CallOptions

ResolveSubmit applies opts onto a fresh CallOptions for Submit.

func ResolveSubscribe

func ResolveSubscribe(opts ...SubscribeOption) *CallOptions

ResolveSubscribe applies opts onto a fresh CallOptions for Subscribe.

func ResolveUpload

func ResolveUpload(opts ...UploadOption) *CallOptions

ResolveUpload applies opts onto a fresh CallOptions for the upload methods.

type RealtimeOption

type RealtimeOption interface {
	// contains filtered or unexported methods
}

RealtimeOption configures Realtime and WSConnect.

type RunOption

type RunOption interface {
	// contains filtered or unexported methods
}

RunOption configures Run.

type StreamOption

type StreamOption interface {
	// contains filtered or unexported methods
}

StreamOption configures Stream.

type SubmitOption

type SubmitOption interface {
	// contains filtered or unexported methods
}

SubmitOption configures Submit.

type SubscribeOption

type SubscribeOption interface {
	// contains filtered or unexported methods
}

SubscribeOption configures Subscribe.

type UploadOption

type UploadOption interface {
	// contains filtered or unexported methods
}

UploadOption configures Upload, UploadFile and UploadImage.