Tapir Link pagination support

Tapir version: 1.0.0-RC1

Scala version: 2.13.8

Hey, first of all I want to say that I really enjoy working with Tapir :)

I wonder if there is any functionality existing for consuming paginated apis with Link headers. I've been trying to use github api which use this pagination model but I couldn't find any existing solution so I ended up implementing custom Codec:

1	  val nextCodec: Codec[String, Option[Next], TextPlain] = Codec.string.mapDecode { value =>
2	    val decode = value
3	      .split("[,;]")
4	      .grouped(2)
5	      .collect {
6	        case Array(nextUrl, rel) if rel.trim == "rel=\"next\"" =>
7	          Uri.parse(nextUrl.substring(1, nextUrl.length - 1)).map(Next)
8	      }
9	      .toVector
10	      .headOption
11	      .sequence
12	    DecodeResult.fromEitherString(value, decode)
13	  }(_.toString)
14	
15	  implicit val nextCodecList: Codec[List[String], Option[Next], TextPlain] =
16	    Codec.listHeadOption(nextCodec).map(_.flatten)(_.some)
17	
18	  private val link  = header[Option[Next]](HeaderNames.Link)

but I'm not very satisfied with the code quality - I had to use flatten at line 16, toString method at line 13 and all of the time I felt like what I'm trying to achieve is hacky - Codec.listHeadOption expect that one there is a header Link I can construct Next instance, but in reality there could be Link header but without any next url in which case I'd simply like this to be none.

Moreover - after extracting next uri I need to somehow extract page parameter, which ended up looking like this:

                val nextPage: Option[Int] = link
                  .flatMap(_.value.querySegments.collectFirst {
                    case KeyValue("page", v, _, _) => v.toIntOption
                  })
                  .flatten

Do you know of any way how I could simplify this? Maybe there is some api that I missed?

Start by reviewing the custom Codec, Codec.listHeadOption, the header[Option[Next]] declaration, and the querySegments page extraction shown in the issue. Define what built-in Link-header pagination should support, including a missing next URL, then verify the resulting API and behavior with focused tests for these cases.