annotations/io.github.kingg22.ktorgen.http/Cookie

Cookie

@Target(allowedTargets = [AnnotationTarget.FUNCTION, AnnotationTarget.VALUE_PARAMETER])

annotation class Cookie(val name: String, val value: String = KTORGEN_DEFAULT_NAME, val maxAge: Int = 0, val expiresTimestamp: Long = -1, val domain: String = "", val path: String = "", val secure: Boolean = false, val httpOnly: Boolean = false, val extensions: Array<Cookie.PairString> = [])(source)

Add a cookie to the request.

If the Cookie plugin is installed, cookies added in the request are ignored. Read Ktor docs for more information.

This annotation is modeled from HttpMessageBuilder.cookie, but adapted to annotation restrictions:

null is not allowed → special values are used to represent absence:
expiresTimestamp = -1L → no expiration.
domain = "" and path = "" → no value assigned.
The extensions field is defined as Array<PairString> for added security and type-safety when mapping cookie extensions.

Example usage:

@Cookie(
    name = "session_id",
    value = "abc123", // required in function
    maxAge = 3600,
    expiresTimestamp = 1735689600000, // 01/01/2025 00:00:00 GMT
    secure = true,
    httpOnly = true,
    extensions = [Cookie.PairString("SameSite", "Strict")],
)
@GET
suspend fun myRequest(@Cookie("yummy_cookie") flavor: String): SecureResponse

// Generated code
this.cookie(
   name = """session_id""",
   value: """abc123""",
   maxAge = 3_600,
   expires = GMTDate(timestamp = 1_735_689_600_000),
   domain = null, // empty string is null
   path = null, // empty string is null
   secure = true,
   httpOnly = true,
   extensions = mapOf("""SameSite""" to """Strict"""),
)