@@ -16,6 +16,7 @@ import * as InternalRecord from "../internal/record.ts"
1616import { type Pipeable , pipeArguments } from "../Pipeable.ts"
1717import * as Predicate from "../Predicate.ts"
1818import * as Record from "../Record.ts"
19+ import * as RegExp_ from "../RegExp.ts"
1920import type * as Schema from "../Schema.ts"
2021import type * as SchemaAST from "../SchemaAST.ts"
2122import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
@@ -484,6 +485,52 @@ export class ErrorParseOptions extends Context.Service<
484485 SchemaAST . ParseOptions
485486> ( ) ( "effect/http-api/HttpApi/ErrorParseOptions" ) { }
486487
488+ /**
489+ * Declares query parameters and headers whose values are only sometimes secret,
490+ * so they are redacted in spans without being modelled as `Redacted`.
491+ *
492+ * **Details**
493+ *
494+ * Names are wire names after encoding, matched like `Headers.isRedactedName`:
495+ * strings case-insensitively, regular expressions by test. A string query name
496+ * also matches the bracketed keys of a nested parameter, such as
497+ * `buildargs[NPM_TOKEN]` for `buildargs`. For the endpoint's client request and
498+ * server span, they extend `UrlParams.CurrentRedactedNames` and
499+ * `Headers.CurrentRedactedNames`. Names from the API, its groups and its
500+ * endpoints are combined. Values sent and decoded are unchanged.
501+ *
502+ * **Gotchas**
503+ *
504+ * - `addHttpApi` copies the added API's annotations onto its groups like any
505+ * other annotation, so a group's own `RedactedNames` replaces them. Repeat
506+ * the names on the group to keep both.
507+ * - Only URL and header attributes use these names. `user_agent.original` and
508+ * the messages of span errors are recorded as is.
509+ *
510+ * **Example** (Redacting Docker build arguments)
511+ *
512+ * ```ts
513+ * import { Schema } from "effect"
514+ * import { HttpApi, HttpApiEndpoint } from "effect/http-api"
515+ *
516+ * const Build = HttpApiEndpoint.post("build", "/build", {
517+ * query: { buildargs: Schema.optional(Schema.Record(Schema.String, Schema.String)) },
518+ * headers: { "x-registry-config": Schema.optional(Schema.String) }
519+ * }).annotate(HttpApi.RedactedNames, {
520+ * query: ["buildargs"],
521+ * headers: ["x-registry-config"]
522+ * })
523+ * ```
524+ *
525+ * @stability unstable
526+ * @category services
527+ * @since 4.0.0
528+ */
529+ export class RedactedNames extends Context . Service < RedactedNames , {
530+ readonly query ?: ReadonlyArray < string | RegExp > | undefined
531+ readonly headers ?: ReadonlyArray < string | RegExp > | undefined
532+ } > ( ) ( "effect/http-api/HttpApi/RedactedNames" ) { }
533+
487534/**
488535 * @internal
489536 */
@@ -510,3 +557,36 @@ export const getSlotParseOptions = (annotations: Context.Context<never>): SlotPa
510557 error : Context . getOrUndefined ( annotations , ErrorParseOptions ) ?? fallback
511558 }
512559}
560+
561+ /**
562+ * @internal
563+ */
564+ export interface EndpointRedactedNames {
565+ readonly query : ReadonlyArray < string | RegExp >
566+ readonly headers : ReadonlyArray < string | RegExp >
567+ }
568+
569+ /**
570+ * Combines the `RedactedNames` of an API, group and endpoint. A string query
571+ * name also matches the bracketed keys of a nested parameter.
572+ *
573+ * @internal
574+ */
575+ export const getEndpointRedactedNames = (
576+ api : Pick < Top , "annotations" > ,
577+ group : HttpApiGroup . Top ,
578+ endpoint : HttpApiEndpoint . Top
579+ ) : EndpointRedactedNames | undefined => {
580+ const query : Array < string | RegExp > = [ ]
581+ const headers : Array < string | RegExp > = [ ]
582+ for ( const annotations of [ api . annotations , group . annotations , endpoint . annotations ] ) {
583+ const options = Context . getOrUndefined ( annotations , RedactedNames )
584+ if ( options === undefined ) continue
585+ for ( const name of options . query ?? [ ] ) {
586+ query . push ( name )
587+ if ( typeof name === "string" ) query . push ( new RegExp ( `^${ RegExp_ . escape ( name ) } \\[` , "i" ) )
588+ }
589+ if ( options . headers !== undefined ) headers . push ( ...options . headers )
590+ }
591+ return query . length === 0 && headers . length === 0 ? undefined : { query, headers }
592+ }
0 commit comments