Skip to main content

Path Configuration

Path configuration applies processing, storage, and delivery rules according to the API path used to store an asset. For example, public avatars and private documents can use different buckets, transformation rules, and delivery strategies in the same konifer.conf file.

Path Configuration is defined in the paths array in konifer.conf. Each object is keyed by a string that specifies the pattern it applies to.

note

Complete regex is not supported. Konifer supports only single (*) and greedy (**) wildcard matching.

Example Configuration​

You can configure the path /public/avatars/** to:

  • Generate three specific thumbnail sizes eagerly upon upload.
  • Limit the height and width of a supplied image.
  • Reject uploads that match a configured upload rule.
rule-definitions {
"blood-and-gore" {
prompts = [
"graphic visible blood",
"open wound with blood",
"bloody injury scene"
]
threshold = 0.72
}
}

paths {
"/public/avatars/**" {
limits {
max-height = 300
max-width = 500
max-pixels = 150KP
}
transform {
eager-variants = [small, medium, large]
}
upload-ruleset {
default = accept
reject-rules = [
{ rule = "blood-and-gore" }
]
}
}
}

Another path can apply different rules. This configuration makes /users/*/profile-picture use a separate S3 bucket and accept only JPEG images:

paths {
"/users/*/profile-picture" {
bucket = "profile-pictures"
allowed-formats = [ jpg ]
}
}

Wildcard Matching​

Wildcards apply one configuration to a group of asset paths.

There are two types of wildcards:

Single Segment (*)​

Matches any single path segment (the text between two slashes).

Example: users/* matches users/123 but not users/123/profile.

Multi-Segment (**)​

Greedily matches zero or more path segments.

Example: users/** matches users/, users/123, and users/123/profile.

Inheritance​

Paths inherit the configuration of parent paths. For any given configuration value, the most-specific configuration property wins.

Example​

Creating an asset at /users/123 uses the users bucket (inherited from the /users path) and also has restrictions on the allowed formats (defined on the more-specific /users/123 path).

paths {
"/users" {
bucket = "users"
}
"/users/123" {
allowed-formats = [ png, jpg ]
}
}

Deep Inheritance​

Konifer's inheritance is deep. Nested configuration values within objects are merged; however, list properties are not merged.

If a child path defines a list or object property (like allowed-formats), the child's property completely overwrites the parent's property.

Example 1: List Overwrite​

Creating an asset at /users/123 does not allow png since list properties are not merged. The png value from the parent is discarded, not merged.

paths {
"/users" {
allowed-formats = [ png ]
}
"/users/123" {
allowed-formats = [ jpg ]
}
}

Example 2: Empty List Overwrite​

Creating an asset at /users/123 does not allow any format. The empty list from the child path overwrites the parent's list.

paths {
"/users" {
allowed-formats = [ png ]
}
"/users/123" {
allowed-formats = []
}
}

Default Path Configuration​

You have two types of defaults to be aware of:

The /** Root Path​

To specify a default configuration that applies to all paths, configure path configuration that is keyed with /**. This path forms the root of the inheritance tree. All other paths inherit from it.

System Defaults​

For any value not defined in the /** path or any of its children, Konifer uses a hardcoded system default. Consult the Path Configuration Reference to determine the system default for each property.

Example​

Storing at /users/123/profile-picture only allows png but storing at /blog/123 would only allow gif.

paths {
"/users/**" {
allowed-formats = [ png ]
}
"/blog/123" {
allowed-formats = [ gif ]
}
}