Metadata value validation is not documented

[Crevil]

Problem description

When setting values in the grpc.Metadata class values are validated but there is no documentation of what the values are restricted to.

The documentation states that keys are normalized but nothing about values.

The validation is performed in the C extension in core/lib/surface/validate_metadata.cc in the function grpc_validate_header_nonbin_value_is_legal.

Reproduction steps

Following example throws Metadata string value "Nordic characters æøå" contains illegal characters:

import * as grpc from 'grpc'

const metadata = new grpc.Metadata()
metadata.set('message', 'Nordic characters æøå')

Environment

• OS name, version and architecture: macOS 10.13.4
• Node version: 9.8.0
• Node installation method: brew
• Package name and version: grpc@1.14.1

Additional context

Failing mocha test

import * as grpc from 'grpc'
import { describe, it } from 'mocha'

describe('grpc Metadata', () => {
  it('should handle nordic characters in strings', () => {
    const metadata = new grpc.Metadata()
    metadata.set('message', 'Nordic characters æøå')
  })
  it('should handle nordic characters in buffers', () => {
    const metadata = new grpc.Metadata()
    metadata.set('message-bin', Buffer.from('Nordic characters æøå'))
  })
})

Result

  grpc Metadata
    1) should handle nordic characters in strings
    ✓ should handle nordic characters in buffers


  1 passing (5ms)
  1 failing

  1) grpc Metadata
       should handle nordic characters in strings:
     Error: Metadata string value "Nordic characters æøå" contains illegal characters
      at validate (node_modules/grpc/src/metadata.js:59:13)
      at Metadata.set (node_modules/grpc/src/metadata.js:74:3)
      at Context.mocha_1.it (test/metadata-spec.ts:8:1)

[murgatroid99]

The short answer is that you're restricted to printable ASCII. To send anything else you need to use binary metadata like in your second test case. The same validator is implemented in this file.

[nicolasnoble]

The documentation is a bit hidden away, but it's available here: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md

Because it's a general protocol thing and not a per-language restriction, this is where we've kept these kind of bits of trivia.

I'm going to keep this one open however, as we might still want to improve documentation overall.

[Crevil]

Thanks, that makes sense. I'll make sure to use the binary representation when handling these values.