YARP — Transform Request

Transform request bao gồm path, query, phiên bản HTTP, phương thức và header. Trong code, chúng được đại diện bởi đối tượng RequestTransformContext và được xử lý bởi các lớp kế thừa từ lớp trừu tượng RequestTransform.

Lưu ý:

• Scheme (http/https), authority và path base của proxy request được lấy từ địa chỉ máy chủ đích (ví dụ https://localhost:10001/Path/Base) và không nên bị sửa đổi bởi transform.
• Header Host có thể được ghi đè bởi transform độc lập với authority, xem RequestHeader bên dưới.
• Thuộc tính PathBase gốc của request không được dùng khi tạo proxy request, xem X-Forwarded.
• Tất cả header của request đến được sao chép sang proxy request theo mặc định, ngoại trừ header Host. Header X-Forwarded cũng được thêm theo mặc định. Các hành vi này có thể được cấu hình bằng các transform sau. Có thể chỉ định thêm header hoặc loại trừ header bằng cách đặt giá trị rỗng.

Dưới đây là các transform tích hợp sẵn được nhận dạng qua key cấu hình chính. Các transform này được áp dụng theo thứ tự được chỉ định trong cấu hình route.

PathPrefix

Sửa đổi path của request bằng cách thêm tiền tố

Cấu hình:

{ "PathPrefix": "/prefix" }

Code:

routeConfig = routeConfig.WithTransformPathPrefix(prefix: "/prefix");

transformBuilderContext.AddPathPrefix(prefix: "/prefix");

Ví dụ: /request/path trở thành /prefix/request/path

PathRemovePrefix

Sửa đổi path của request bằng cách xóa tiền tố

Cấu hình:

{ "PathRemovePrefix": "/prefix" }

Code:

routeConfig = routeConfig.WithTransformPathRemovePrefix(prefix: "/prefix");

transformBuilderContext.AddPathRemovePrefix(prefix: "/prefix");

Ví dụ: /prefix/request/path trở thành /request/path; /prefix2/request/path không bị thay đổi.

Transform này xóa tiền tố khớp khỏi path của request. Việc khớp được thực hiện trên ranh giới path segment (/). Nếu tiền tố không khớp thì không có thay đổi nào được thực hiện.

PathSet

Thay thế path của request bằng giá trị được chỉ định

Cấu hình:

{ "PathSet": "/newpath" }

Code:

routeConfig = routeConfig.WithTransformPathSet(path: "/newpath");

transformBuilderContext.AddPathSet(path: "/newpath");

Ví dụ: /request/path trở thành /newpath

PathPattern

Thay thế path của request bằng một template pattern

Cấu hình:

{ "PathPattern": "/my/{plugin}/api/{**remainder}" }

Code:

routeConfig = routeConfig.WithTransformPathRouteValues(
    pattern: new PathString("/my/{plugin}/api/{**remainder}"));

transformBuilderContext.AddPathRouteValues(
    pattern: new PathString("/my/{plugin}/api/{**remainder}"));

Transform này đặt path của request với giá trị đã cho và thay thế bất kỳ segment {} nào bằng giá trị route tương ứng. Các segment {} không có giá trị route khớp sẽ bị xóa. Segment {} cuối cùng có thể được đánh dấu là {**remainder} để chỉ ra đây là segment catch-all có thể chứa nhiều path segment.

Ví dụ:

QueryValueParameter

Thêm hoặc thay thế tham số trong query string của request

Cấu hình:

{
  "QueryValueParameter": "foo",
  "Append": "bar"
}

Code:

routeConfig = routeConfig.WithTransformQueryValue(
    queryKey: "foo", value: "bar", append: true);

transformBuilderContext.AddQueryValue(
    queryKey: "foo", value: "bar", append: true);

Ví dụ:

QueryRouteParameter

Thêm hoặc thay thế tham số query string bằng giá trị từ cấu hình route

Cấu hình:

{
  "QueryRouteParameter": "foo",
  "Append": "remainder"
}

Code:

routeConfig = routeConfig.WithTransformQueryRouteValue(
    queryKey: "foo", routeValueKey: "remainder", append: true);

transformBuilderContext.AddQueryRouteValue(
    queryKey: "foo", routeValueKey: "remainder", append: true);

Ví dụ:

QueryRemoveParameter

Xóa tham số được chỉ định khỏi query string của request

Cấu hình:

{ "QueryRemoveParameter": "foo" }

Code:

routeConfig = routeConfig.WithTransformQueryRemoveKey(queryKey: "foo");

transformBuilderContext.AddQueryRemoveKey(queryKey: "foo");

Ví dụ:

HttpMethodChange

Thay đổi HTTP method được dùng trong request

Cấu hình:

{
  "HttpMethodChange": "PUT",
  "Set": "POST"
}

Code:

routeConfig = routeConfig.WithTransformHttpMethodChange(
    fromHttpMethod: HttpMethods.Put, toHttpMethod: HttpMethods.Post);

transformBuilderContext.AddHttpMethodChange(
    fromHttpMethod: HttpMethods.Put, toHttpMethod: HttpMethods.Post);

Transform này sẽ đổi các request PUT thành POST.

RequestHeadersCopy

Đặt có sao chép header của request đến sang request đi hay không

Cấu hình:

{ "RequestHeadersCopy": "false" }

Code:

routeConfig = routeConfig.WithTransformCopyRequestHeaders(copy: false);

transformBuilderContext.CopyRequestHeaders = false;

Đặt xem có sao chép tất cả header của request đến vào proxy request không. Cài đặt này được bật mặc định và có thể tắt bằng cách cấu hình transform với giá trị false. Các transform tham chiếu đến header cụ thể vẫn sẽ chạy nếu cài đặt này bị tắt.

RequestHeaderOriginalHost

Chỉ định xem header Host của request đến có nên được sao chép sang proxy request không

Cấu hình:

{ "RequestHeaderOriginalHost": "true" }

Code:

routeConfig = routeConfig.WithTransformUseOriginalHostHeader(useOriginal: true);

transformBuilderContext.AddOriginalHost(true);

Cài đặt này bị tắt mặc định và có thể bật bằng cách cấu hình transform với giá trị true. Các transform tham chiếu trực tiếp đến header Host sẽ ghi đè transform này.

RequestHeader

Thêm hoặc thay thế header của request

Cấu hình:

{
  "RequestHeader": "MyHeader",
  "Set": "MyValue"
}

Code:

routeConfig = routeConfig.WithTransformRequestHeader(
    headerName: "MyHeader", value: "MyValue", append: false);

transformBuilderContext.AddRequestHeader(
    headerName: "MyHeader", value: "MyValue", append: false);

Ví dụ:

MyHeader: MyValue

Transform này đặt hoặc nối thêm giá trị cho header được đặt tên. Set thay thế bất kỳ header hiện có nào. Append thêm một header bổ sung với giá trị đã cho. Lưu ý: việc đặt "" làm giá trị header không được khuyến nghị và có thể gây ra hành vi không xác định.

RequestHeaderRouteValue

Thêm hoặc thay thế header bằng giá trị từ cấu hình route

Cấu hình:

{
  "RequestHeaderRouteValue": "MyHeader",
  "Set": "MyRouteKey"
}

Code:

routeConfig = routeConfig.WithTransformRequestHeaderRouteValue(
    headerName: "MyHeader", routeValueKey: "key", append: false);

transformBuilderContext.AddRequestHeaderRouteValue(
    headerName: "MyHeader", routeValueKey: "key", append: false);

Ví dụ:

RequestHeaderRemove

Xóa header của request

Cấu hình:

{
  "RequestHeaderRemove": "MyHeader"
}

Code:

routeConfig = routeConfig.WithTransformRequestHeaderRemove(headerName: "MyHeader");

transformBuilderContext.AddRequestHeaderRemove(headerName: "MyHeader");

Transform này xóa header có tên được chỉ định.

RequestHeadersAllowed

Cấu hình:

{
  "RequestHeadersAllowed": "Header1;header2"
}

Code:

routeConfig = routeConfig.WithTransformRequestHeadersAllowed("Header1", "header2");

transformBuilderContext.AddRequestHeadersAllowed("Header1", "header2");

YARP sao chép hầu hết header request sang proxy request theo mặc định (xem RequestHeadersCopy). Một số mô hình bảo mật chỉ cho phép proxy các header cụ thể. Transform này tắt RequestHeadersCopy và chỉ sao chép các header được chỉ định.

Lưu ý rằng có một số header YARP không sao chép mặc định vì chúng đặc thù cho kết nối hoặc nhạy cảm về bảo mật (ví dụ Connection, Alt-Svc). Việc đặt những tên header đó vào danh sách cho phép sẽ bỏ qua hạn chế đó nhưng rất không được khuyến khích.

Ví dụ: chỉ header1 và header2 được sao chép vào proxy request.

X-Forwarded

Thêm header với thông tin về request gốc của client

Hành động "Off" hoàn toàn tắt transform.

Cấu hình:

{
  "X-Forwarded": "Set",
  "For": "Remove",
  "Proto": "Append",
  "Prefix": "Off",
  "HeaderPrefix": "X-Forwarded-"
}

Code:

routeConfig = routeConfig.WithTransformXForwarded(
  headerPrefix = "X-Forwarded-",
  ForwardedTransformActions xDefault = ForwardedTransformActions.Set,
  ForwardedTransformActions? xFor = null,
  ForwardedTransformActions? xHost = null,
  ForwardedTransformActions? xProto = null,
  ForwardedTransformActions? xPrefix = null);

transformBuilderContext.AddXForwarded(ForwardedTransformActions.Set);
transformBuilderContext.AddXForwardedFor(headerName: "X-Forwarded-For", ForwardedTransformActions.Append);
transformBuilderContext.AddXForwardedHost(headerName: "X-Forwarded-Host", ForwardedTransformActions.Append);
transformBuilderContext.AddXForwardedProto(headerName: "X-Forwarded-Proto", ForwardedTransformActions.Off);
transformBuilderContext.AddXForwardedPrefix(headerName: "X-Forwarded-Prefix", ForwardedTransformActions.Remove);

Ví dụ:

X-Forwarded-For: 5.5.5.5
X-Forwarded-Proto: https
X-Forwarded-Host: IncomingHost:5000
X-Forwarded-Prefix: /path/base

Tắt header mặc định:

{ "X-Forwarded": "Off" }

transformBuilderContext.UseDefaultForwarders = false;

Khi proxy kết nối đến máy chủ đích, kết nối đó độc lập với kết nối client đã tạo tới proxy. Máy chủ đích có thể cần thông tin kết nối gốc để kiểm tra bảo mật và tạo URI tuyệt đối cho các liên kết và chuyển hướng đúng cách.

Transform này được bật mặc định ngay cả khi không được chỉ định trong cấu hình route.

{Prefix}For: Giá trị header được lấy từ HttpContext.Connection.RemoteIpAddress — địa chỉ IP của caller trước đó.

{Prefix}Proto: Giá trị header được lấy từ HttpContext.Request.Scheme — cho biết caller trước đó đã sử dụng HTTP hay HTTPS.

{Prefix}Host: Giá trị header được lấy từ header Host của request đến. Điều này độc lập với RequestHeaderOriginalHost.

{Prefix}Prefix: Giá trị header được lấy từ HttpContext.Request.PathBase.

Forwarded

Thêm header với thông tin về request gốc của client (theo chuẩn RFC)

Cấu hình:

{
  "Forwarded": "by,for,host,proto",
  "ByFormat": "Random",
  "ForFormat": "IpAndPort",
  "Action": "Append"
}

Code:

routeConfig = routeConfig.WithTransformForwarded(
    useHost: true, useProto: true, forFormat: NodeFormat.IpAndPort, 
    ByFormat: NodeFormat.Random, action: ForwardedTransformAction.Append);

Ví dụ:

Forwarded: proto=https;host="localhost:5001";for="[::1]:20173";by=_YQuN68tm6

Header Forwarded được định nghĩa bởi RFC 7239. Nó hợp nhất nhiều chức năng giống với các header X-Forwarded không chính thức.

Bật transform này sẽ tắt các transform X-Forwarded mặc định vì chúng mang thông tin tương tự ở định dạng khác. Các transform X-Forwarded vẫn có thể được bật tường minh.

Định dạng ByFormat và ForFormat:

ClientCert

Chuyển tiếp chứng chỉ client được dùng trên kết nối đến như một header tới đích

Cấu hình:

{ "ClientCert": "X-Client-Cert" }

Code:

routeConfig = routeConfig.WithTransformClientCertHeader(headerName: "X-Client-Cert");

transformBuilderContext.AddClientCertHeader(headerName: "X-Client-Cert");

Ví dụ:

X-Client-Cert: SSdtIGEgY2VydGlmaWNhdGU...

Vì kết nối đến và đi là độc lập, cần có cách truyền chứng chỉ client đến sang máy chủ đích. Transform này khiến chứng chỉ client (lấy từ HttpContext.Connection.ClientCertificate) được mã hóa Base64 và đặt làm giá trị cho tên header đã cho.

Transform này chỉ áp dụng nếu chứng chỉ client đã có trên kết nối.