Upgrading from Ktor 1 to Ktor 2

[chris-christensen]

I am doing a Ktor upgrade to the latest version (2.1.1) and it seems like I need to update kompendium as well.

In the old version I had:

    route("/status") {
        notarizedGet(
            GetInfo<Unit, String>(
                summary = "Status",
                description = "Returns server status for monitoring",
                responseInfo = ResponseInfo(
                    status = HttpStatusCode.OK,
                    description = "Should be returned as long as the server is available",
                    mediaTypes = listOf("text/plain; charset=UTF-8")
                ),
                tags = setOf("Status")
            )
        ) {
            // return 'true' because the e2etest scripts call bw-node's startall.sh which wants text output
            call.respond(HttpStatusCode.OK, "OK true")
        }
    }

which I think becomes:

    route("/status") {
        GetInfo.builder {
            summary("Status")
            description("Returns server status for monitoring")
            response {
                responseCode(HttpStatusCode.OK)
                description("Should be returned as long as the server is available")
                responseType(typeOf<String>())
            }
            tags("Status")
            get {
                // return 'true' because the e2etest scripts call bw-node's startall.sh which wants text output
                call.respond(HttpStatusCode.OK, "OK true")
            }
        }
    }

but I was not sure what if anything I can do with mediaTypes

also some places I have

                canThrow = setOf(
                    ExceptionInfo<Unit>(
                        responseType = typeOf<Unit>(),
                        status = HttpStatusCode.ServiceUnavailable,
                        description = "The database is unavailable"
                    )
                ),

and don't see what that maps to

or

securitySchemes = setOf("default"),

Are there more examples that I am missing?

[brizzbuzz]

Hey, have you had a chance to check out the docs?

Kompendium v3 (the version compatible with ktor 2) is pretty much a ground up rewrite, and a lot of breaking changes were made. I also rewrote the docs, since the old docs kinda sucked.

If you have any questions after reading through the docs definitely feel free to post them here :)

One thing that stands out in your code snippet is that you don't appear to have installed the NotarizedRoute plugin. Definitely make sure to check that section out in the docs, it is new for ktor 2 since ktor 1 did not have route-level plugins.

Additionally, canThrow is now canRespond. See here for more info

Also, always worth checking out the playground for working examples, the docs for the playground are here

[chris-christensen]

Thanks Ryan, that helps. I had been thinking NotarizedRoute was installed only once in all the examples I had not caught on that I would use that per route. But each of the examples only had one route. And is this obsolete? securitySchemes = setOf("default"), From: Ryan Brink ***@***.***> Reply-To: bkbnio/kompendium ***@***.***> Date: Thursday, October 6, 2022 at 5:55 PM To: bkbnio/kompendium ***@***.***> Cc: Chris Christensen ***@***.***>, Author ***@***.***> Subject: [External] Re: [bkbnio/kompendium] Upgrade (Discussion #346) Hey, have you had a chance to check out the docs<https://isolate.menlosecurity.com/1/3735928037/https:/bkbn.gitbook.io/kompendium>? Kompendium v3 (the version compatible with ktor 2) is pretty much a ground up rewrite, and a lot of breaking changes were made. I also rewrote the docs, since the old docs kinda sucked. If you have any questions after reading through the docs definitely feel free to post them here :) One thing that stands out in your code snippet is that you don't appear to have installed the NotarizedRoute plugin. Definitely make sure to check that section out in the docs, it is new for ktor 2 since ktor 1 did not have route-level plugins. Additionally, canThrow is now canRespond. See here<https://isolate.menlosecurity.com/1/3735928037/https:/bkbn.gitbook.io/kompendium/index-1/notarized_route#error-info> for more info — Reply to this email directly, view it on GitHub<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/discussions/346#discussioncomment-3818838>, or unsubscribe<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/notifications/unsubscribe-auth/AZUH5XQXLDZ4EKS5DXQO673WB5YHRANCNFSM6AAAAAAQ7CPX3A>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>> American Express made the following annotations "This message and any attachments are solely for the intended recipient and may contain confidential or privileged information. If you are not the intended recipient, any disclosure, copying, use, or distribution of the information included in this message and any attachments is prohibited. If you have received this communication in error, please notify us by reply e-mail and immediately and permanently delete this message and any attachments. Thank you." American Express a ajouté le commentaire suivant Ce courrier et toute pièce jointe qu'il contient sont réservés au seul destinataire indiqué et peuvent contenir des renseignements confidentiels et privilégiés. Si vous n'êtes pas le destinataire prévu, toute divulgation, duplication, utilisation ou distribution du courrier ou de toute pièce jointe est interdite. Si vous avez reçu cette communication par erreur, veuillez nous en aviser par courrier et détruire immédiatement le courrier et les pièces jointes. Merci.

[brizzbuzz]

Security scheme definitions have been adjusted a bit, simple example here https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/AuthPlayground.kt#L61-L69

[brizzbuzz]

but once you define the available schemes, kompendium will determine the auth for the route by introspecting the Route metadata, so that is all you need to do

[chris-christensen]

Ahhhhhh, OK, thanks! From: Ryan Brink ***@***.***> Reply-To: bkbnio/kompendium ***@***.***> Date: Friday, October 7, 2022 at 8:09 AM To: bkbnio/kompendium ***@***.***> Cc: Chris Christensen ***@***.***>, Author ***@***.***> Subject: [External] Re: [bkbnio/kompendium] Upgrading from Ktor 1 to Ktor 2 (Discussion #346) Security scheme definitions have been adjusted a bit, simple example here https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/AuthPlayground.kt#L61-L69<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/AuthPlayground.kt#L61-L69> — Reply to this email directly, view it on GitHub<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/discussions/346#discussioncomment-3823730>, or unsubscribe<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/notifications/unsubscribe-auth/AZUH5XUAYQP6ZENRH353OJTWCA4JZANCNFSM6AAAAAAQ7CPX3A>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>> American Express made the following annotations "This message and any attachments are solely for the intended recipient and may contain confidential or privileged information. If you are not the intended recipient, any disclosure, copying, use, or distribution of the information included in this message and any attachments is prohibited. If you have received this communication in error, please notify us by reply e-mail and immediately and permanently delete this message and any attachments. Thank you." American Express a ajouté le commentaire suivant Ce courrier et toute pièce jointe qu'il contient sont réservés au seul destinataire indiqué et peuvent contenir des renseignements confidentiels et privilégiés. Si vous n'êtes pas le destinataire prévu, toute divulgation, duplication, utilisation ou distribution du courrier ou de toute pièce jointe est interdite. Si vous avez reçu cette communication par erreur, veuillez nous en aviser par courrier et détruire immédiatement le courrier et les pièces jointes. Merci.

[chris-christensen]

I think I misunderstood something in the examples. In the examples they never handle documenting multiple routes. I had done route("/default/") { install(NotarizedRoute()) { PutInfo.builder { … } } put { … } } route("/minimum") { install(NotarizedRoute()) { PostInfo.builder { … } } post { … } } But since that gets the error io.ktor.server.application.DuplicatePluginException: Please make sure that you use unique name for the plugin and don't install it twice I can see that I am wrong. But… what do I want instead of that second install? From: Chris Christensen ***@***.***> Date: Friday, October 7, 2022 at 7:57 AM To: bkbnio/kompendium ***@***.***>, bkbnio/kompendium ***@***.***> Cc: Author ***@***.***> Subject: Re: [External] Re: [bkbnio/kompendium] Upgrade (Discussion #346) Thanks Ryan, that helps. I had been thinking NotarizedRoute was installed only once in all the examples I had not caught on that I would use that per route. But each of the examples only had one route. And is this obsolete? securitySchemes = setOf("default"), From: Ryan Brink ***@***.***> Reply-To: bkbnio/kompendium ***@***.***> Date: Thursday, October 6, 2022 at 5:55 PM To: bkbnio/kompendium ***@***.***> Cc: Chris Christensen ***@***.***>, Author ***@***.***> Subject: [External] Re: [bkbnio/kompendium] Upgrade (Discussion #346) Hey, have you had a chance to check out the docs<https://isolate.menlosecurity.com/1/3735928037/https:/bkbn.gitbook.io/kompendium>? Kompendium v3 (the version compatible with ktor 2) is pretty much a ground up rewrite, and a lot of breaking changes were made. I also rewrote the docs, since the old docs kinda sucked. If you have any questions after reading through the docs definitely feel free to post them here :) One thing that stands out in your code snippet is that you don't appear to have installed the NotarizedRoute plugin. Definitely make sure to check that section out in the docs, it is new for ktor 2 since ktor 1 did not have route-level plugins. Additionally, canThrow is now canRespond. See here<https://isolate.menlosecurity.com/1/3735928037/https:/bkbn.gitbook.io/kompendium/index-1/notarized_route#error-info> for more info — Reply to this email directly, view it on GitHub<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/discussions/346#discussioncomment-3818838>, or unsubscribe<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/notifications/unsubscribe-auth/AZUH5XQXLDZ4EKS5DXQO673WB5YHRANCNFSM6AAAAAAQ7CPX3A>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>> American Express made the following annotations "This message and any attachments are solely for the intended recipient and may contain confidential or privileged information. If you are not the intended recipient, any disclosure, copying, use, or distribution of the information included in this message and any attachments is prohibited. If you have received this communication in error, please notify us by reply e-mail and immediately and permanently delete this message and any attachments. Thank you." American Express a ajouté le commentaire suivant Ce courrier et toute pièce jointe qu'il contient sont réservés au seul destinataire indiqué et peuvent contenir des renseignements confidentiels et privilégiés. Si vous n'êtes pas le destinataire prévu, toute divulgation, duplication, utilisation ou distribution du courrier ou de toute pièce jointe est interdite. Si vous avez reçu cette communication par erreur, veuillez nous en aviser par courrier et détruire immédiatement le courrier et les pièces jointes. Merci.

[brizzbuzz]

I added a nested route with documentation to the basic example in the playground :)

https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt

what you have looks mostly right, though you don't seem to be assigning the PutInfo to the put variable? ie https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt#L78

not sure why you are getting an error about duplicate plugins, if you post a more complete example that would be helpful

[chris-christensen]

Nevermind, figured it out From: Chris Christensen ***@***.***> Date: Friday, October 14, 2022 at 11:55 AM To: bkbnio/kompendium ***@***.***>, bkbnio/kompendium ***@***.***> Cc: Author ***@***.***> Subject: Re: [External] Re: [bkbnio/kompendium] Upgrade (Discussion #346) I think I misunderstood something in the examples. In the examples they never handle documenting multiple routes. I had done route("/default/") { install(NotarizedRoute()) { PutInfo.builder { … } } put { … } } route("/minimum") { install(NotarizedRoute()) { PostInfo.builder { … } } post { … } } But since that gets the error io.ktor.server.application.DuplicatePluginException: Please make sure that you use unique name for the plugin and don't install it twice I can see that I am wrong. But… what do I want instead of that second install? From: Chris Christensen ***@***.***> Date: Friday, October 7, 2022 at 7:57 AM To: bkbnio/kompendium ***@***.***>, bkbnio/kompendium ***@***.***> Cc: Author ***@***.***> Subject: Re: [External] Re: [bkbnio/kompendium] Upgrade (Discussion #346) Thanks Ryan, that helps. I had been thinking NotarizedRoute was installed only once in all the examples I had not caught on that I would use that per route. But each of the examples only had one route. And is this obsolete? securitySchemes = setOf("default"), From: Ryan Brink ***@***.***> Reply-To: bkbnio/kompendium ***@***.***> Date: Thursday, October 6, 2022 at 5:55 PM To: bkbnio/kompendium ***@***.***> Cc: Chris Christensen ***@***.***>, Author ***@***.***> Subject: [External] Re: [bkbnio/kompendium] Upgrade (Discussion #346) Hey, have you had a chance to check out the docs<https://isolate.menlosecurity.com/1/3735928037/https:/bkbn.gitbook.io/kompendium>? Kompendium v3 (the version compatible with ktor 2) is pretty much a ground up rewrite, and a lot of breaking changes were made. I also rewrote the docs, since the old docs kinda sucked. If you have any questions after reading through the docs definitely feel free to post them here :) One thing that stands out in your code snippet is that you don't appear to have installed the NotarizedRoute plugin. Definitely make sure to check that section out in the docs, it is new for ktor 2 since ktor 1 did not have route-level plugins. Additionally, canThrow is now canRespond. See here<https://isolate.menlosecurity.com/1/3735928037/https:/bkbn.gitbook.io/kompendium/index-1/notarized_route#error-info> for more info — Reply to this email directly, view it on GitHub<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/discussions/346#discussioncomment-3818838>, or unsubscribe<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/notifications/unsubscribe-auth/AZUH5XQXLDZ4EKS5DXQO673WB5YHRANCNFSM6AAAAAAQ7CPX3A>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>> American Express made the following annotations "This message and any attachments are solely for the intended recipient and may contain confidential or privileged information. If you are not the intended recipient, any disclosure, copying, use, or distribution of the information included in this message and any attachments is prohibited. If you have received this communication in error, please notify us by reply e-mail and immediately and permanently delete this message and any attachments. Thank you." American Express a ajouté le commentaire suivant Ce courrier et toute pièce jointe qu'il contient sont réservés au seul destinataire indiqué et peuvent contenir des renseignements confidentiels et privilégiés. Si vous n'êtes pas le destinataire prévu, toute divulgation, duplication, utilisation ou distribution du courrier ou de toute pièce jointe est interdite. Si vous avez reçu cette communication par erreur, veuillez nous en aviser par courrier et détruire immédiatement le courrier et les pièces jointes. Merci.

[chris-christensen]

thanks From: Ryan Brink ***@***.***> Reply-To: bkbnio/kompendium ***@***.***> Date: Friday, October 14, 2022 at 12:57 PM To: bkbnio/kompendium ***@***.***> Cc: Chris Christensen ***@***.***>, Author ***@***.***> Subject: [External] Re: [bkbnio/kompendium] Upgrading from Ktor 1 to Ktor 2 (Discussion #346) I added a nested route with documentation to the basic example in the playground :) https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt> what you have looks mostly right, though you don't seem to be assigning the PutInfo to the put variable? ie https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt#L78<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt#L78> not sure why you are getting an error about duplicate plugins, if you post a more complete example that would be helpful — Reply to this email directly, view it on GitHub<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/discussions/346#discussioncomment-3881901>, or unsubscribe<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/notifications/unsubscribe-auth/AZUH5XRYICQ4KJSZ64X5N2DWDG3KLANCNFSM6AAAAAAQ7CPX3A>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>> American Express made the following annotations "This message and any attachments are solely for the intended recipient and may contain confidential or privileged information. If you are not the intended recipient, any disclosure, copying, use, or distribution of the information included in this message and any attachments is prohibited. If you have received this communication in error, please notify us by reply e-mail and immediately and permanently delete this message and any attachments. Thank you." American Express a ajouté le commentaire suivant Ce courrier et toute pièce jointe qu'il contient sont réservés au seul destinataire indiqué et peuvent contenir des renseignements confidentiels et privilégiés. Si vous n'êtes pas le destinataire prévu, toute divulgation, duplication, utilisation ou distribution du courrier ou de toute pièce jointe est interdite. Si vous avez reçu cette communication par erreur, veuillez nous en aviser par courrier et détruire immédiatement le courrier et les pièces jointes. Merci.

[chris-christensen]

The reason I was getting the error about duplicate plugins was that I was installing on the get method and then again on the put or the post method. I figure it out. From: Ryan Brink ***@***.***> Reply-To: bkbnio/kompendium ***@***.***> Date: Friday, October 14, 2022 at 12:57 PM To: bkbnio/kompendium ***@***.***> Cc: Chris Christensen ***@***.***>, Author ***@***.***> Subject: [External] Re: [bkbnio/kompendium] Upgrading from Ktor 1 to Ktor 2 (Discussion #346) I added a nested route with documentation to the basic example in the playground :) https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt> what you have looks mostly right, though you don't seem to be assigning the PutInfo to the put variable? ie https://github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt#L78<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/blob/main/playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt#L78> not sure why you are getting an error about duplicate plugins, if you post a more complete example that would be helpful — Reply to this email directly, view it on GitHub<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/bkbnio/kompendium/discussions/346#discussioncomment-3881901>, or unsubscribe<https://isolate.menlosecurity.com/1/3735928037/https:/github.com/notifications/unsubscribe-auth/AZUH5XRYICQ4KJSZ64X5N2DWDG3KLANCNFSM6AAAAAAQ7CPX3A>. You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>> American Express made the following annotations "This message and any attachments are solely for the intended recipient and may contain confidential or privileged information. If you are not the intended recipient, any disclosure, copying, use, or distribution of the information included in this message and any attachments is prohibited. If you have received this communication in error, please notify us by reply e-mail and immediately and permanently delete this message and any attachments. Thank you." American Express a ajouté le commentaire suivant Ce courrier et toute pièce jointe qu'il contient sont réservés au seul destinataire indiqué et peuvent contenir des renseignements confidentiels et privilégiés. Si vous n'êtes pas le destinataire prévu, toute divulgation, duplication, utilisation ou distribution du courrier ou de toute pièce jointe est interdite. Si vous avez reçu cette communication par erreur, veuillez nous en aviser par courrier et détruire immédiatement le courrier et les pièces jointes. Merci.