| 1 | package config |
| 2 | |
| 3 | import ( |
| 4 | "github.com/ipfs/boxo/gateway" |
| 5 | ) |
| 6 | |
| 7 | const ( |
| 8 | DefaultInlineDNSLink = false |
| 9 | DefaultDeserializedResponses = true |
| 10 | DefaultDisableHTMLErrors = false |
| 11 | DefaultExposeRoutingAPI = true |
| 12 | DefaultDiagnosticServiceURL = "https://check.ipfs.network" |
| 13 | DefaultAllowCodecConversion = false |
| 14 | |
| 15 | // Gateway limit defaults from boxo |
| 16 | DefaultRetrievalTimeout = gateway.DefaultRetrievalTimeout |
| 17 | DefaultMaxRequestDuration = gateway.DefaultMaxRequestDuration |
| 18 | DefaultMaxConcurrentRequests = gateway.DefaultMaxConcurrentRequests |
| 19 | DefaultMaxRangeRequestFileSize = 0 // 0 means no limit |
| 20 | ) |
| 21 | |
| 22 | type GatewaySpec struct { |
| 23 | // Paths is explicit list of path prefixes that should be handled by |
| 24 | // this gateway. Example: `["/ipfs", "/ipns"]` |
| 25 | Paths []string |
| 26 | |
| 27 | // UseSubdomains indicates whether or not this gateway uses subdomains |
| 28 | // for IPFS resources instead of paths. That is: http://CID.ipfs.GATEWAY/... |
| 29 | // |
| 30 | // If this flag is set, any /ipns/$id and/or /ipfs/$id paths in Paths |
| 31 | // will be permanently redirected to http://$id.[ipns|ipfs].$gateway/. |
| 32 | // |
| 33 | // We do not support using both paths and subdomains for a single domain |
| 34 | // for security reasons (Origin isolation). |
| 35 | UseSubdomains bool |
| 36 | |
| 37 | // NoDNSLink configures this gateway to _not_ resolve DNSLink for the FQDN |
| 38 | // provided in `Host` HTTP header. |
| 39 | NoDNSLink bool |
| 40 | |
| 41 | // InlineDNSLink configures this gateway to always inline DNSLink names |
| 42 | // (FQDN) into a single DNS label in order to interop with wildcard TLS certs |
| 43 | // and Origin per CID isolation provided by rules like https://publicsuffix.org |
| 44 | InlineDNSLink Flag |
| 45 | |
| 46 | // DeserializedResponses configures this gateway to respond to deserialized |
| 47 | // responses. Disabling this option enables a Trustless Gateway, as per: |
| 48 | // https://specs.ipfs.tech/http-gateways/trustless-gateway/. |
| 49 | DeserializedResponses Flag |
| 50 | } |
| 51 | |
| 52 | // Gateway contains options for the HTTP gateway server. |
| 53 | type Gateway struct { |
| 54 | // HTTPHeaders configures the headers that should be returned by this |
| 55 | // gateway. |
| 56 | HTTPHeaders map[string][]string // HTTP headers to return with the gateway |
| 57 | |
| 58 | // RootRedirect is the path to which requests to `/` on this gateway |
| 59 | // should be redirected. |
| 60 | RootRedirect string |
| 61 | |
| 62 | // NoFetch configures the gateway to _not_ fetch blocks in response to |
| 63 | // requests. |
| 64 | NoFetch bool |
| 65 | |
| 66 | // NoDNSLink configures the gateway to _not_ perform DNS TXT record |
| 67 | // lookups in response to requests with values in `Host` HTTP header. |
| 68 | // This flag can be overridden per FQDN in PublicGateways. |
| 69 | NoDNSLink bool |
| 70 | |
| 71 | // DeserializedResponses configures this gateway to respond to deserialized |
| 72 | // requests. Disabling this option enables a Trustless only gateway, as per: |
| 73 | // https://specs.ipfs.tech/http-gateways/trustless-gateway/. This can |
| 74 | // be overridden per FQDN in PublicGateways. |
| 75 | DeserializedResponses Flag |
| 76 | |
| 77 | // AllowCodecConversion enables automatic conversion between codecs when |
| 78 | // the requested format differs from the block's native codec (e.g., |
| 79 | // converting dag-pb or dag-cbor to dag-json). When disabled, the gateway |
| 80 | // returns 406 Not Acceptable for codec mismatches per IPIP-524. |
| 81 | AllowCodecConversion Flag |
| 82 | |
| 83 | // DisableHTMLErrors disables pretty HTML pages when an error occurs. Instead, a `text/plain` |
| 84 | // page will be sent with the raw error message. |
| 85 | DisableHTMLErrors Flag |
| 86 | |
| 87 | // PublicGateways configures behavior of known public gateways. |
| 88 | // Each key is a fully qualified domain name (FQDN). |
| 89 | PublicGateways map[string]*GatewaySpec |
| 90 | |
| 91 | // ExposeRoutingAPI configures the gateway port to expose |
| 92 | // routing system as HTTP API at /routing/v1 (https://specs.ipfs.tech/routing/http-routing-v1/). |
| 93 | ExposeRoutingAPI Flag |
| 94 | |
| 95 | // RetrievalTimeout enforces a maximum duration for content retrieval: |
| 96 | // - Time to first byte: If the gateway cannot start writing the response within |
| 97 | // this duration (e.g., stuck searching for providers), a 504 Gateway Timeout |
| 98 | // is returned. |
| 99 | // - Time between writes: After the first byte, the timeout resets each time new |
| 100 | // bytes are written to the client. If the gateway cannot write additional data |
| 101 | // within this duration after the last successful write, the response is terminated. |
| 102 | // This helps free resources when the gateway gets stuck looking for providers |
| 103 | // or cannot retrieve the requested content. |
| 104 | // A value of 0 disables this timeout. |
| 105 | RetrievalTimeout *OptionalDuration `json:",omitempty"` |
| 106 | |
| 107 | // MaxRequestDuration is an absolute deadline for the entire request. |
| 108 | // Unlike RetrievalTimeout (which resets on each data write and catches |
| 109 | // stalled transfers), this is a hard limit on the total time a request |
| 110 | // can take. Returns 504 Gateway Timeout when exceeded. |
| 111 | // This protects the gateway from edge cases and slow client attacks. |
| 112 | // A value of 0 uses the default (1 hour). |
| 113 | MaxRequestDuration *OptionalDuration `json:",omitempty"` |
| 114 | |
| 115 | // MaxConcurrentRequests limits concurrent HTTP requests handled by the gateway. |
| 116 | // Requests beyond this limit receive 429 Too Many Requests with Retry-After header. |
| 117 | // A value of 0 disables the limit. |
| 118 | MaxConcurrentRequests *OptionalInteger `json:",omitempty"` |
| 119 | |
| 120 | // MaxRangeRequestFileSize limits the maximum file size for HTTP range requests. |
| 121 | // Range requests for files larger than this limit return 501 Not Implemented. |
| 122 | // This protects against CDN issues with large file range requests and prevents |
| 123 | // excessive bandwidth consumption. A value of 0 disables the limit. |
| 124 | MaxRangeRequestFileSize *OptionalBytes `json:",omitempty"` |
| 125 | |
| 126 | // DiagnosticServiceURL is the URL for a service to diagnose CID retrievability issues. |
| 127 | // When the gateway returns a 504 Gateway Timeout error, an "Inspect retrievability of CID" |
| 128 | // button will be shown that links to this service with the CID appended as ?cid=<CID-to-diagnose>. |
| 129 | // Set to empty string to disable the button. |
| 130 | DiagnosticServiceURL *OptionalString `json:",omitempty"` |
| 131 | } |