1/*
2 *
3 * Copyright 2024 gRPC authors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18
19package encoding
20
21import (
22 "strings"
23
24 "google.golang.org/grpc/mem"
25)
26
27// CodecV2 defines the interface gRPC uses to encode and decode messages. Note
28// that implementations of this interface must be thread safe; a CodecV2's
29// methods can be called from concurrent goroutines.
30type CodecV2 interface {
31 // Marshal returns the wire format of v. The buffers in the returned
32 // [mem.BufferSlice] must have at least one reference each, which will be freed
33 // by gRPC when they are no longer needed.
34 Marshal(v any) (out mem.BufferSlice, err error)
35 // Unmarshal parses the wire format into v. Note that data will be freed as soon
36 // as this function returns. If the codec wishes to guarantee access to the data
37 // after this function, it must take its own reference that it frees when it is
38 // no longer needed.
39 Unmarshal(data mem.BufferSlice, v any) error
40 // Name returns the name of the Codec implementation. The returned string
41 // will be used as part of content type in transmission. The result must be
42 // static; the result cannot change between calls.
43 Name() string
44}
45
46// RegisterCodecV2 registers the provided CodecV2 for use with all gRPC clients and
47// servers.
48//
49// The CodecV2 will be stored and looked up by result of its Name() method, which
50// should match the content-subtype of the encoding handled by the CodecV2. This
51// is case-insensitive, and is stored and looked up as lowercase. If the
52// result of calling Name() is an empty string, RegisterCodecV2 will panic. See
53// Content-Type on
54// https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for
55// more details.
56//
57// If both a Codec and CodecV2 are registered with the same name, the CodecV2
58// will be used.
59//
60// NOTE: this function must only be called during initialization time (i.e. in
61// an init() function), and is not thread-safe. If multiple Codecs are
62// registered with the same name, the one registered last will take effect.
63func RegisterCodecV2(codec CodecV2) {
64 if codec == nil {
65 panic("cannot register a nil CodecV2")
66 }
67 if codec.Name() == "" {
68 panic("cannot register CodecV2 with empty string result for Name()")
69 }
70 contentSubtype := strings.ToLower(codec.Name())
71 registeredCodecs[contentSubtype] = codec
72}
73
74// GetCodecV2 gets a registered CodecV2 by content-subtype, or nil if no CodecV2 is
75// registered for the content-subtype.
76//
77// The content-subtype is expected to be lowercase.
78func GetCodecV2(contentSubtype string) CodecV2 {
79 c, _ := registeredCodecs[contentSubtype].(CodecV2)
80 return c
81}