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.
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 ]
}
}