Skip to content

gRPC: Enable HTTP endpoint with TLS support - #6668

Draft
carbolymer wants to merge 2 commits into
masterfrom
mgalazyn/feature/enable-rpc-http
Draft

gRPC: Enable HTTP endpoint with TLS support#6668
carbolymer wants to merge 2 commits into
masterfrom
mgalazyn/feature/enable-rpc-http

Conversation

@carbolymer

@carbolymer carbolymer commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Description

Adds configuration for the node's gRPC server to listen over HTTP/2 instead of only a unix socket, in plaintext (h2c) or with TLS.

  • New CLI flags --grpc-listen-address/--grpc-listen-port (config keys RpcListenAddress/RpcListenPort) switch the server from the unix socket to HTTP/2.
    The listen address accepts an IPv4 or IPv6 address and defaults to 127.0.0.1.
  • New CLI flags --grpc-tls-certificate/--grpc-tls-private-key/--grpc-tls-chain-certificate (config keys RpcTlsCertificateFile/RpcTlsPrivateKeyFile/RpcTlsChainCertificateFiles) switch the HTTP/2 endpoint to TLS.
  • Conflicting or incomplete combinations are rejected at configuration parse time.
    For example, a unix socket path together with a listen port, or a TLS private key without a certificate.
  • A new RPC.ServerListening trace announces the endpoint the gRPC server is listening on at startup.

Also fixes --port and the tracer socket CLI options.
They previously parsed port numbers with a plain Int/Word16 read and silently wrapped out-of-range values, for example 70000 became 4464.
They now reject out-of-range and non-decimal input.

This depends on the RpcEndpoint/RpcTlsFiles types added in IntersectMBO/cardano-api#1322, which is not yet merged or released to CHaP.
The cardano-rpc bound in cardano-node.cabal is still ^>= 11.2 and needs bumping to ^>= 11.3 once that release lands.
CI will stay red until then.

Checklist

  • Commit sequence broadly makes sense and commits have useful messages
  • New tests are added if needed and existing tests are updated. These may include:
    • golden tests
    • property tests
    • roundtrip tests
    • integration tests
      See Running tests for more details
  • Any changes are noted in the CHANGELOG.md for affected package
    • cardano-node-chairman, cardano-submit-api and cardano-testnet instead need a
      changelog fragment in <package>/.changes/, because their CHANGELOG.md is generated
      from fragments at release time. Copy _TEMPLATE.yml from that directory, or run
      nix run github:input-output-hk/cardano-dev#herald -- new
  • The version bounds in .cabal files are updated
  • CI passes. See note on CI. The following CI checks are required:
    • Code is linted with hlint. See .github/workflows/check-hlint.yml to get the hlint version
    • Code is formatted with stylish-haskell. See .github/workflows/stylish-haskell.yml to get the stylish-haskell version
    • Code builds on Linux, MacOS and Windows for ghc-9.6 and ghc-9.12
  • Self-reviewed the diff

Note on CI

If your PR is from a fork, the necessary CI jobs won't trigger automatically for security reasons.
You will need to get someone with write privileges. Please contact IOG node developers to do this
for you.

Parse the new RpcEndpoint sum type from node configuration
(RpcListenAddress/RpcListenPort) and CLI (--grpc-listen-address/
--grpc-listen-port). A configured listen port makes the gRPC server
listen on plaintext TCP instead of the unix socket; configuring both a
socket path and a listen port is rejected at configuration parse time.
The listen address defaults to 127.0.0.1.
Add RpcTlsCertificateFile/RpcTlsPrivateKeyFile/RpcTlsChainCertificateFiles
configuration keys and --grpc-tls-certificate/--grpc-tls-private-key/
--grpc-tls-chain-certificate CLI flags. Certificate and private key must
be configured together and require a TCP listen port; violations are
rejected at configuration parse time.
@carbolymer
carbolymer force-pushed the mgalazyn/feature/enable-rpc-http branch from 700ac67 to 299f4a9 Compare August 28, 2026 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant