Support point in time searches (#5151)

* Support point in time searches
* Support override of ResolveUrl

This allows us to special case pit searches to remove the index parameter.
Includes new usage tests for doc generation.

Author: stevejgordon

src/Nest/CommonAbstractions/Request/ApiUrls.cs

@@ -14,6 +14,9 @@ namespace Nest
 	/// </summary>
 	internal class ApiUrls
 	{
+		private static readonly RouteValues EmptyRouteValues = new();
+		private readonly string _errorMessageSuffix;
+
 		/// <summary>
 		/// If the spec only defines a single non parameterizable route this allows us to shortcircuit and avoid hitting
 		/// the cached string builders.
@@ -25,9 +28,7 @@ internal class ApiUrls
 		/// <see cref="UrlLookup.Matches"/> allows us to quickly find the right url to use in the list.
 		/// </summary>
 		public Dictionary<int, List<UrlLookup>> Routes { get; }
-
-		private readonly string _errorMessageSuffix;
-
+		
 		/// <summary> Only intended to be created once per request and stored in a static </summary>
 		internal ApiUrls(string[] routes)
 		{

src/Nest/CommonAbstractions/Request/RequestBase.cs

@@ -80,8 +80,9 @@ protected RequestBase(Func<RouteValues, RouteValues> pathSelector)
 
 		internal abstract ApiUrls ApiUrls { get;  }
 
-		string IRequest.GetUrl(IConnectionSettingsValues settings) => ApiUrls.Resolve(RequestState.RouteValues, settings);
+		string IRequest.GetUrl(IConnectionSettingsValues settings) => ResolveUrl(RequestState.RouteValues, settings);
 
+		protected virtual string ResolveUrl(RouteValues routeValues, IConnectionSettingsValues settings) => ApiUrls.Resolve(routeValues, settings);
 
 		/// <summary>
 		/// Allows a request implementation to set certain request parameter defaults, use sparingly!

src/Nest/Search/Search/PointInTime/PointInTime.cs

@@ -0,0 +1,57 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Runtime.Serialization;
+using Elasticsearch.Net.Utf8Json;
+
+namespace Nest
+{
+	[InterfaceDataContract]
+	[ReadAs(typeof(PointInTime))]
+	public interface IPointInTime
+	{
+		/// <summary>
+		/// The ID of the point in time.
+		/// </summary>
+		[DataMember(Name = "id")]
+		string Id { get; set; }
+
+		/// <summary>
+		/// How long to extend the TTL of the point in time.
+		/// </summary>
+		[DataMember(Name = "keep_alive")]
+		Time KeepAlive { get; set; }
+	}
+
+	public class PointInTime : IPointInTime
+	{
+		/// <param name="id">The ID of the point in time.</param>
+		public PointInTime(string id) => Id = id;
+
+		/// <param name="id">The ID of the point in time.</param>
+		/// <param name="keepAlive">How long to extend the TTL of the point in time.</param>
+		public PointInTime(string id, Time keepAlive)
+		{
+			Id = id;
+			KeepAlive = keepAlive;
+		}
+
+		/// <inheritdoc />
+		public string Id { get; set; }
+
+		/// <inheritdoc />
+		public Time KeepAlive { get; set; }
+	}
+
+	public class PointInTimeDescriptor : DescriptorBase<PointInTimeDescriptor, IPointInTime>, IPointInTime
+	{
+		public PointInTimeDescriptor(string id) => Self.Id = id;
+		
+		string IPointInTime.Id { get; set; }
+		Time IPointInTime.KeepAlive { get; set; }
+		
+		/// <inheritdoc cref="IPointInTime.KeepAlive" />
+		public PointInTimeDescriptor KeepAlive(Time id) => Assign(id, (a, v) => a.KeepAlive = v);
+	}
+}

src/Nest/Search/Search/SearchRequest.cs

@@ -166,6 +166,9 @@ public partial interface ISearchRequest : ITypedSearchRequest
 		/// </summary>
 		[DataMember(Name = "version")]
 		bool? Version { get; set; }
+
+		[DataMember(Name = "pit")]
+		IPointInTime PointInTime { get; set; }
 	}
 
 	[ReadAs(typeof(SearchRequest<>))]
@@ -227,6 +230,8 @@ public partial class SearchRequest
 		public bool? TrackTotalHits { get; set; }
 		/// <inheritdoc />
 		public bool? Version { get; set; }
+		/// <inheritdoc />
+		public IPointInTime PointInTime { get; set; }
 
 		protected override HttpMethod HttpMethod =>
 			RequestState.RequestParameters?.ContainsQueryString("source") == true
@@ -236,6 +241,16 @@ public partial class SearchRequest
 		Type ITypedSearchRequest.ClrType => null;
 
 		protected sealed override void RequestDefaults(SearchRequestParameters parameters) => TypedKeys = true;
+
+		protected override string ResolveUrl(RouteValues routeValues, IConnectionSettingsValues settings)
+		{
+			if (Self.PointInTime is object && !string.IsNullOrEmpty(Self.PointInTime.Id) && routeValues.ContainsKey("index"))
+			{
+				routeValues.Remove("index");
+			}
+
+			return base.ResolveUrl(routeValues, settings);
+		}
 	}
 
 	[DataContract]
@@ -281,6 +296,7 @@ public partial class SearchDescriptor<TInferDocument> where TInferDocument : cla
 		bool? ISearchRequest.TrackScores { get; set; }
 		bool? ISearchRequest.TrackTotalHits { get; set; }
 		bool? ISearchRequest.Version { get; set; }
+		IPointInTime ISearchRequest.PointInTime { get; set; }
 
 		protected sealed override void RequestDefaults(SearchRequestParameters parameters) => TypedKeys();
 
@@ -438,5 +454,26 @@ public SearchDescriptor<TInferDocument> Rescore(Func<RescoringDescriptor<TInferD
 
 		/// <inheritdoc cref="ISearchRequest.TrackTotalHits" />
 		public SearchDescriptor<TInferDocument> TrackTotalHits(bool? trackTotalHits = true) => Assign(trackTotalHits, (a, v) => a.TrackTotalHits = v);
+
+		/// <inheritdoc cref="ISearchRequest.PointInTime" />
+		public SearchDescriptor<TInferDocument> PointInTime(string pitId)
+		{
+			Self.PointInTime = new PointInTime(pitId);
+			return this;
+		}
+
+		/// <inheritdoc cref="ISearchRequest.PointInTime" />
+		public SearchDescriptor<TInferDocument> PointInTime(string pitId, Func<PointInTimeDescriptor, IPointInTime> pit) =>
+			Assign(pit, (a, v) => a.PointInTime = v?.Invoke(new PointInTimeDescriptor(pitId)));
+
+		protected override string ResolveUrl(RouteValues routeValues, IConnectionSettingsValues settings)
+		{
+			if (Self.PointInTime is object && !string.IsNullOrEmpty(Self.PointInTime.Id) && routeValues.ContainsKey("index"))
+			{
+				routeValues.Remove("index");
+			}
+
+			return base.ResolveUrl(routeValues, settings);
+		}
 	}
 }

src/Nest/Search/Search/SearchResponse.cs

@@ -111,6 +111,11 @@ public interface ISearchResponse<out TDocument> : IResponse where TDocument : cl
 		/// Gets the total number of documents matching the search query criteria
 		/// </summary>
 		long Total { get; }
+
+		/// <summary>
+		/// When a search is made over a point in time, this will be the ID of the point in time.
+		/// </summary>
+		string PointInTimeId { get; }
 	}
 
 	public class SearchResponse<TDocument> : ResponseBase, ISearchResponse<TDocument> where TDocument : class
@@ -191,5 +196,9 @@ public class SearchResponse<TDocument> : ResponseBase, ISearchResponse<TDocument
 		/// <inheritdoc />
 		[IgnoreDataMember]
 		public long Total => HitsMetadata?.Total.Value ?? -1;
+
+		/// <inheritdoc />
+		[DataMember(Name = "pit_id")]
+		public string PointInTimeId { get; internal set; }
 	}
 }