Debian Codegraph @

pubsub/natspubsub/nats.go

raw
1 // Copyright 2019 The Go Cloud Development Kit Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 // Package natspubsub provides a pubsub implementation for NATS.io. Use OpenTopic to
16 // construct a *pubsub.Topic, and/or OpenSubscription to construct a
17 // *pubsub.Subscription. This package uses gob to encode and decode driver.Message to
18 // []byte.
19 //
20 // # URLs
21 //
22 // For pubsub.OpenTopic and pubsub.OpenSubscription, natspubsub registers
23 // for the scheme "nats".
24 // The default URL opener will connect to a default server based on the
25 // environment variable "NATS_SERVER_URL".
26 //
27 // For servers that support it (NATS Server 2.2.0 or later), messages can
28 // be encoded using native NATS message headers, and native message content.
29 // This provides full support for non-Go clients. Versions prior to 2.2.0
30 // uses gob.Encoder to encode the message headers and content, which limits
31 // the subscribers only to Go clients.
32 // To use this feature, set the query parameter "natsv2" in the URL.
33 // If no value is provided, it assumes the value is true. Otherwise, the value
34 // needs to be parsable as a boolean. For example:
35 // - nats://mysubject?natsv2
36 // - nats://mysubject?natsv2=true
37 //
38 // This feature can also be enabled by setting the UseV2 field in the
39 // URLOpener.
40 // If the server does not support this feature, any attempt to use it will
41 // result in an error.
42 // Using native NATS message headers and content is more efficient than using
43 // gob.Encoder, and allows non-Go clients to subscribe to the topic and
44 // receive messages. It is recommended to use this feature if the server
45 // supports it.
46 //
47 // To customize the URL opener, or for more details on the URL format,
48 // see URLOpener.
49 // See https://gocloud.dev/concepts/urls/ for background information.
50 //
51 // # Message Delivery Semantics
52 //
53 // NATS supports at-most-semantics; applications need not call Message.Ack,
54 // and must not call Message.Nack.
55 // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery
56 // for more background.
57 //
58 // # As
59 //
60 // natspubsub exposes the following types for As:
61 // - Topic: *nats.Conn
62 // - Subscription: *nats.Subscription
63 // - Message.BeforeSend: None for v1, *nats.Msg for v2.
64 // - Message.AfterSend: None.
65 // - Message: *nats.Msg
66 package natspubsub // import "gocloud.dev/pubsub/natspubsub"
67
68 import (
69 "bytes"
70 "context"
71 "encoding/gob"
72 "errors"
73 "fmt"
74 "net/url"
75 "os"
76 "path"
77 "regexp"
78 "strconv"
79 "strings"
80 "sync"
81 "time"
82
83 "github.com/nats-io/nats.go"
84
85 "gocloud.dev/gcerrors"
86 "gocloud.dev/pubsub"
87 "gocloud.dev/pubsub/batcher"
88 "gocloud.dev/pubsub/driver"
89 )
90
91 var errNotInitialized = errors.New("natspubsub: topic not initialized")
92
93 var recvBatcherOpts = &batcher.Options{
94 // NATS has at-most-once semantics, meaning once it delivers a message, the
95 // message won't be delivered again.
96 // Therefore, we can't allow the portable type to read-ahead and queue any
97 // messages; they might end up undelivered if the user never calls Receive
98 // to get them. Setting both the MaxBatchSize and MaxHandlers to one means
99 // that we'll only return a message at a time, which should be immediately
100 // returned to the user.
101 //
102 // Note: there is a race condition where the original Receive that
103 // triggered a call to ReceiveBatch ends up failing (e.g., due to a
104 // Done context), and ReceiveBatch returns a message that ends up being
105 // queued for the next Receive. That message is at risk of being dropped.
106 // This seems OK.
107 MaxBatchSize: 1,
108 MaxHandlers: 1, // max concurrency for receives
109 }
110
111 func init() {
112 o := new(defaultDialer)
113 pubsub.DefaultURLMux().RegisterTopic(Scheme, o)
114 pubsub.DefaultURLMux().RegisterSubscription(Scheme, o)
115 }
116
117 // defaultDialer dials a default NATS server based on the environment
118 // variable "NATS_SERVER_URL".
119 type defaultDialer struct {
120 init sync.Once
121 err error
122
123 opener URLOpener
124 openerV2 URLOpener
125 }
126
127 func (o *defaultDialer) defaultConn(ctx context.Context) error {
128 o.init.Do(func() {
129 serverURL := os.Getenv("NATS_SERVER_URL")
130 if serverURL == "" {
131 o.err = errors.New("NATS_SERVER_URL environment variable not set")
132 return
133 }
134 conn, err := nats.Connect(serverURL)
135 if err != nil {
136 o.err = fmt.Errorf("failed to dial NATS_SERVER_URL %q: %v", serverURL, err)
137 return
138 }
139 o.opener = URLOpener{Connection: conn}
140 o.openerV2 = URLOpener{Connection: conn, UseV2: true}
141 })
142 return o.err
143 }
144
145 type serverVersion struct {
146 major, minor, patch int
147 }
148
149 func (o *defaultDialer) OpenTopicURL(ctx context.Context, u *url.URL) (*pubsub.Topic, error) {
150 err := o.defaultConn(ctx)
151 if err != nil {
152 return nil, fmt.Errorf("open topic %v: failed to open default connection: %v", u, err)
153 }
154 useV2, err := queryUseV2(u.Query())
155 if err != nil {
156 return nil, fmt.Errorf("open topic %v: %v", u, err)
157 }
158 if useV2 {
159 return o.openerV2.OpenTopicURL(ctx, u)
160 }
161 return o.opener.OpenTopicURL(ctx, u)
162 }
163
164 func (o *defaultDialer) OpenSubscriptionURL(ctx context.Context, u *url.URL) (*pubsub.Subscription, error) {
165 err := o.defaultConn(ctx)
166 if err != nil {
167 return nil, fmt.Errorf("open subscription %v: failed to open default connection: %v", u, err)
168 }
169 useV2, err := queryUseV2(u.Query())
170 if err != nil {
171 return nil, fmt.Errorf("open subscription %v: %v", u, err)
172 }
173 if useV2 {
174 return o.openerV2.OpenSubscriptionURL(ctx, u)
175 }
176 return o.opener.OpenSubscriptionURL(ctx, u)
177 }
178
179 var semVerRegexp = regexp.MustCompile(`\Av?([0-9]+)\.?([0-9]+)?\.?([0-9]+)?`)
180
181 func parseServerVersion(version string) (serverVersion, error) {
182 m := semVerRegexp.FindStringSubmatch(version)
183 if m == nil {
184 return serverVersion{}, errors.New("failed to parse server version")
185 }
186 var (
187 major, minor, patch int
188 err error
189 )
190 major, err = strconv.Atoi(m[1])
191 if err != nil {
192 return serverVersion{}, fmt.Errorf("failed to parse server version major number %q: %v", m[1], err)
193 }
194 minor, err = strconv.Atoi(m[2])
195 if err != nil {
196 return serverVersion{}, fmt.Errorf("failed to parse server version minor number %q: %v", m[2], err)
197 }
198 patch, err = strconv.Atoi(m[3])
199 if err != nil {
200 return serverVersion{}, fmt.Errorf("failed to parse server version patch number %q: %v", m[3], err)
201 }
202 return serverVersion{major: major, minor: minor, patch: patch}, nil
203 }
204
205 // Scheme is the URL scheme natspubsub registers its URLOpeners under on pubsub.DefaultMux.
206 const Scheme = "nats"
207
208 // URLOpener opens NATS URLs like "nats://mysubject?natsv2=true".
209 //
210 // The URL host+path is used as the subject.
211 //
212 // No query parameters are supported.
213 type URLOpener struct {
214 // Connection to use for communication with the server.
215 Connection *nats.Conn
216 // TopicOptions specifies the options to pass to OpenTopic.
217 TopicOptions TopicOptions
218 // SubscriptionOptions specifies the options to pass to OpenSubscription.
219 SubscriptionOptions SubscriptionOptions
220 // UseV2 indicates whether the NATS Server is at least version 2.2.0.
221 UseV2 bool
222 }
223
224 const natsV2QueryParameter = "natsv2"
225
226 // OpenTopicURL opens a pubsub.Topic based on u.
227 func (o *URLOpener) OpenTopicURL(ctx context.Context, u *url.URL) (*pubsub.Topic, error) {
228 for param := range u.Query() {
229 if strings.ToLower(param) == natsV2QueryParameter {
230 continue
231 }
232 return nil, fmt.Errorf("open topic %v: invalid query parameter %s", u, param)
233 }
234 subject := path.Join(u.Host, u.Path)
235 if o.UseV2 {
236 return OpenTopicV2(o.Connection, subject, &o.TopicOptions)
237 }
238 return OpenTopic(o.Connection, subject, &o.TopicOptions)
239 }
240
241 // OpenSubscriptionURL opens a pubsub.Subscription based on u.
242 func (o *URLOpener) OpenSubscriptionURL(ctx context.Context, u *url.URL) (*pubsub.Subscription, error) {
243 opts := o.SubscriptionOptions
244 for param, values := range u.Query() {
245 switch strings.ToLower(param) {
246 case natsV2QueryParameter:
247 continue
248 case "queue":
249 if len(values) != 1 {
250 return nil, fmt.Errorf("open subscription %v: invalid query parameter %s", u, param)
251 }
252 opts.Queue = values[0]
253 default:
254 return nil, fmt.Errorf("open subscription %v: invalid query parameter %s", u, param)
255 }
256 }
257 subject := path.Join(u.Host, u.Path)
258 if o.UseV2 {
259 return OpenSubscriptionV2(o.Connection, subject, &opts)
260 }
261 return OpenSubscription(o.Connection, subject, &opts)
262 }
263
264 // TopicOptions sets options for constructing a *pubsub.Topic backed by NATS.
265 type TopicOptions struct{}
266
267 // SubscriptionOptions sets options for constructing a *pubsub.Subscription
268 // backed by NATS.
269 type SubscriptionOptions struct {
270 // Queue sets the subscription as a QueueSubcription.
271 // For more info, see https://docs.nats.io/nats-concepts/queue.
272 Queue string
273 }
274
275 type topic struct {
276 useV2 bool
277 nc *nats.Conn
278 subj string
279 }
280
281 // OpenTopic returns a *pubsub.Topic for use with NATS.
282 // The subject is the NATS Subject; for more info, see
283 // https://nats.io/documentation/writing_applications/subjects.
284 func OpenTopic(nc *nats.Conn, subject string, _ *TopicOptions) (*pubsub.Topic, error) {
285 dt, err := openTopic(nc, subject, false)
286 if err != nil {
287 return nil, err
288 }
289 return pubsub.NewTopic(dt, nil), nil
290 }
291
292 // OpenTopicV2 returns a *pubsub.Topic for use with NATS at least version 2.2.0.
293 // This changes the encoding of the message as, starting with version 2.2.0, NATS supports message headers.
294 // In previous versions the message headers were encoded along with the message content using gob.Encoder,
295 // which limits the subscribers only to Go clients.
296 // This implementation uses native NATS message headers, and native message content, which provides full support
297 // for non-Go clients.
298 func OpenTopicV2(nc *nats.Conn, subject string, _ *TopicOptions) (*pubsub.Topic, error) {
299 dt, err := openTopic(nc, subject, true)
300 if err != nil {
301 return nil, err
302 }
303 return pubsub.NewTopic(dt, nil), nil
304 }
305
306 // openTopic returns the driver for OpenTopic. This function exists so the test
307 // harness can get the driver interface implementation if it needs to.
308 func openTopic(nc *nats.Conn, subject string, useV2 bool) (driver.Topic, error) {
309 if nc == nil {
310 return nil, errors.New("natspubsub: nats.Conn is required")
311 }
312 if useV2 {
313 sv, err := parseServerVersion(nc.ConnectedServerVersion())
314 if err != nil {
315 return nil, fmt.Errorf("failed to parse NATS server version %q: %v", nc.ConnectedServerVersion(), err)
316 }
317 // Check if the server version is at least 2.2.0.
318 if sv.major < 2 && sv.minor < 2 {
319 return nil, fmt.Errorf("natspubsub: NATS server version %q is not supported", nc.ConnectedServerVersion())
320 }
321 }
322 return &topic{nc: nc, subj: subject, useV2: useV2}, nil
323 }
324
325 // SendBatch implements driver.Topic.SendBatch.
326 func (t *topic) SendBatch(ctx context.Context, msgs []*driver.Message) error {
327 if t == nil || t.nc == nil {
328 return errNotInitialized
329 }
330
331 for _, m := range msgs {
332 err := ctx.Err()
333 if err != nil {
334 return err
335 }
336
337 if t.useV2 {
338 err = t.sendMessageV2(m)
339 } else {
340 err = t.sendMessage(m)
341 }
342 if err != nil {
343 return err
344 }
345 }
346 // Per specification this is supposed to only return after
347 // a message has been sent. Normally NATS is very efficient
348 // at sending messages in batches on its own and also handles
349 // disconnected buffering during a reconnect event. We will
350 // let NATS handle this for now. If needed we could add a
351 // FlushWithContext() call which ensures the connected server
352 // has processed all the messages.
353 return nil
354 }
355
356 func (t *topic) sendMessage(m *driver.Message) error {
357 // TODO(jba): benchmark message encoding to see if it's
358 // worth reusing a buffer.
359 payload, err := encodeMessage(m)
360 if err != nil {
361 return err
362 }
363 if m.BeforeSend != nil {
364 asFunc := func(i any) bool { return false }
365 if err := m.BeforeSend(asFunc); err != nil {
366 return err
367 }
368 }
369 if err = t.nc.Publish(t.subj, payload); err != nil {
370 return err
371 }
372 if m.AfterSend != nil {
373 asFunc := func(i any) bool { return false }
374 if err := m.AfterSend(asFunc); err != nil {
375 return err
376 }
377 }
378 return nil
379 }
380
381 func (t *topic) sendMessageV2(m *driver.Message) error {
382 msg := encodeMessageV2(m, t.subj)
383 if m.BeforeSend != nil {
384 asFunc := func(i any) bool {
385 if nm, ok := i.(**nats.Msg); ok {
386 *nm = msg
387 return true
388 }
389 return false
390 }
391 if err := m.BeforeSend(asFunc); err != nil {
392 return err
393 }
394 }
395
396 if err := t.nc.PublishMsg(msg); err != nil {
397 return err
398 }
399
400 if m.AfterSend != nil {
401 asFunc := func(i any) bool { return false }
402 if err := m.AfterSend(asFunc); err != nil {
403 return err
404 }
405 }
406 return nil
407 }
408
409 // IsRetryable implements driver.Topic.IsRetryable.
410 func (*topic) IsRetryable(error) bool { return false }
411
412 // As implements driver.Topic.As.
413 func (t *topic) As(i any) bool {
414 c, ok := i.(**nats.Conn)
415 if !ok {
416 return false
417 }
418 *c = t.nc
419 return true
420 }
421
422 // ErrorAs implements driver.Topic.ErrorAs
423 func (*topic) ErrorAs(error, any) bool {
424 return false
425 }
426
427 // ErrorCode implements driver.Topic.ErrorCode
428 func (*topic) ErrorCode(err error) gcerrors.ErrorCode {
429 switch err {
430 case nil:
431 return gcerrors.OK
432 case context.Canceled:
433 return gcerrors.Canceled
434 case errNotInitialized:
435 return gcerrors.NotFound
436 case nats.ErrBadSubject:
437 return gcerrors.FailedPrecondition
438 case nats.ErrAuthorization:
439 return gcerrors.PermissionDenied
440 case nats.ErrMaxPayload, nats.ErrReconnectBufExceeded:
441 return gcerrors.ResourceExhausted
442 }
443 return gcerrors.Unknown
444 }
445
446 // Close implements driver.Topic.Close.
447 func (*topic) Close() error { return nil }
448
449 type subscription struct {
450 useV2 bool
451 nc *nats.Conn
452 nsub *nats.Subscription
453 nextID int
454 }
455
456 // OpenSubscription returns a *pubsub.Subscription representing a NATS subscription or NATS queue subscription.
457 // The subject is the NATS Subject to subscribe to;
458 // for more info, see https://nats.io/documentation/writing_applications/subjects.
459 func OpenSubscription(nc *nats.Conn, subject string, opts *SubscriptionOptions) (*pubsub.Subscription, error) {
460 ds, err := openSubscription(nc, subject, opts, false)
461 if err != nil {
462 return nil, err
463 }
464 return pubsub.NewSubscription(ds, recvBatcherOpts, nil), nil
465 }
466
467 // OpenSubscriptionV2 returns a *pubsub.Subscription representing a NATS subscription or NATS queue subscription
468 // for use with NATS at least version 2.2.0.
469 // This changes the encoding of the message as, starting with version 2.2.0, NATS supports message headers.
470 // In previous versions the message headers were encoded along with the message content using gob.Encoder,
471 // which limits the subscribers only to Go clients.
472 // This implementation uses native NATS message headers, and native message content, which provides full support
473 // for non-Go clients.
474 func OpenSubscriptionV2(nc *nats.Conn, subject string, opts *SubscriptionOptions) (*pubsub.Subscription, error) {
475 ds, err := openSubscription(nc, subject, opts, true)
476 if err != nil {
477 return nil, err
478 }
479 return pubsub.NewSubscription(ds, recvBatcherOpts, nil), nil
480 }
481
482 func openSubscription(nc *nats.Conn, subject string, opts *SubscriptionOptions, useV2 bool) (driver.Subscription, error) {
483 var sub *nats.Subscription
484 var err error
485 if opts != nil && opts.Queue != "" {
486 sub, err = nc.QueueSubscribeSync(subject, opts.Queue)
487 } else {
488 sub, err = nc.SubscribeSync(subject)
489 }
490 if err != nil {
491 return nil, err
492 }
493 return &subscription{nc: nc, nsub: sub, nextID: 1, useV2: useV2}, nil
494 }
495
496 // ReceiveBatch implements driver.ReceiveBatch.
497 func (s *subscription) ReceiveBatch(ctx context.Context, _ int) ([]*driver.Message, error) {
498 if s == nil || s.nsub == nil {
499 return nil, nats.ErrBadSubscription
500 }
501
502 msg, err := s.nsub.NextMsg(100 * time.Millisecond)
503 if err != nil {
504 if err == nats.ErrTimeout {
505 return nil, nil
506 }
507 return nil, err
508 }
509
510 var dm *driver.Message
511 if s.useV2 {
512 dm, err = decodeMessageV2(msg)
513 } else {
514 dm, err = decode(msg)
515 }
516 if err != nil {
517 return nil, err
518 }
519 dm.LoggableID = fmt.Sprintf("msg #%d", s.nextID)
520 s.nextID++
521 return []*driver.Message{dm}, nil
522 }
523
524 // Convert NATS msgs to *driver.Message.
525 func decode(msg *nats.Msg) (*driver.Message, error) {
526 if msg == nil {
527 return nil, nats.ErrInvalidMsg
528 }
529 var dm driver.Message
530 if err := decodeMessage(msg.Data, &dm); err != nil {
531 return nil, err
532 }
533 dm.AckID = -1 // Not applicable to NATS
534 dm.AsFunc = messageAsFunc(msg)
535 return &dm, nil
536 }
537
538 func messageAsFunc(msg *nats.Msg) func(any) bool {
539 return func(i any) bool {
540 p, ok := i.(**nats.Msg)
541 if !ok {
542 return false
543 }
544 *p = msg
545 return true
546 }
547 }
548
549 // SendAcks implements driver.Subscription.SendAcks.
550 func (s *subscription) SendAcks(ctx context.Context, ids []driver.AckID) error {
551 // Ack is a no-op.
552 return nil
553 }
554
555 // CanNack implements driver.CanNack.
556 func (s *subscription) CanNack() bool { return false }
557
558 // SendNacks implements driver.Subscription.SendNacks. It should never be called
559 // because we return false for CanNack.
560 func (s *subscription) SendNacks(ctx context.Context, ids []driver.AckID) error {
561 panic("unreachable")
562 }
563
564 // IsRetryable implements driver.Subscription.IsRetryable.
565 func (s *subscription) IsRetryable(error) bool { return false }
566
567 // As implements driver.Subscription.As.
568 func (s *subscription) As(i any) bool {
569 c, ok := i.(**nats.Subscription)
570 if !ok {
571 return false
572 }
573 *c = s.nsub
574 return true
575 }
576
577 // ErrorAs implements driver.Subscription.ErrorAs
578 func (*subscription) ErrorAs(error, any) bool {
579 return false
580 }
581
582 // ErrorCode implements driver.Subscription.ErrorCode
583 func (*subscription) ErrorCode(err error) gcerrors.ErrorCode {
584 switch err {
585 case nil:
586 return gcerrors.OK
587 case context.Canceled:
588 return gcerrors.Canceled
589 case errNotInitialized, nats.ErrBadSubscription:
590 return gcerrors.NotFound
591 case nats.ErrBadSubject, nats.ErrTypeSubscription:
592 return gcerrors.FailedPrecondition
593 case nats.ErrAuthorization:
594 return gcerrors.PermissionDenied
595 case nats.ErrMaxMessages, nats.ErrSlowConsumer:
596 return gcerrors.ResourceExhausted
597 case nats.ErrTimeout:
598 return gcerrors.DeadlineExceeded
599 }
600 return gcerrors.Unknown
601 }
602
603 // Close implements driver.Subscription.Close.
604 func (*subscription) Close() error { return nil }
605
606 func encodeMessage(dm *driver.Message) ([]byte, error) {
607 var buf bytes.Buffer
608 enc := gob.NewEncoder(&buf)
609 if len(dm.Metadata) == 0 {
610 return dm.Body, nil
611 }
612 if err := enc.Encode(dm.Metadata); err != nil {
613 return nil, err
614 }
615 if err := enc.Encode(dm.Body); err != nil {
616 return nil, err
617 }
618 return buf.Bytes(), nil
619 }
620
621 func decodeMessage(data []byte, dm *driver.Message) error {
622 buf := bytes.NewBuffer(data)
623 dec := gob.NewDecoder(buf)
624 if err := dec.Decode(&dm.Metadata); err != nil {
625 // This may indicate a normal NATS message, so just treat as the body.
626 dm.Metadata = nil
627 dm.Body = data
628 return nil
629 }
630 return dec.Decode(&dm.Body)
631 }
632
633 func queryUseV2(q url.Values) (bool, error) {
634 if len(q) == 0 {
635 return false, nil
636 }
637 v, ok := q[natsV2QueryParameter]
638 if !ok {
639 return false, nil
640 }
641
642 if len(v) == 0 {
643 // If the query parameter was provided without any value i.e. nats://mysubject?natsv2
644 // it assumes the value is true.
645 return true, nil
646 }
647 if len(v) > 1 {
648 return false, fmt.Errorf("invalid query parameter %s - multiple values provided", natsV2QueryParameter)
649 }
650 if v[0] == "" {
651 return true, nil
652 }
653 useV2, err := strconv.ParseBool(v[0])
654 if err != nil {
655 return false, fmt.Errorf("invalid query parameter %s - value either needs to be parsable as a boolean or empty", natsV2QueryParameter)
656 }
657 return useV2, nil
658 }
659
660 func encodeMessageV2(dm *driver.Message, sub string) *nats.Msg {
661 var header nats.Header
662 if dm.Metadata != nil {
663 header = nats.Header{}
664 for k, v := range dm.Metadata {
665 header[url.QueryEscape(k)] = []string{url.QueryEscape(v)}
666 }
667 }
668 return &nats.Msg{
669 Subject: sub,
670 Data: dm.Body,
671 Header: header,
672 }
673 }
674
675 func decodeMessageV2(msg *nats.Msg) (*driver.Message, error) {
676 if msg == nil {
677 return nil, nats.ErrInvalidMsg
678 }
679
680 dm := driver.Message{
681 AsFunc: messageAsFunc(msg),
682 Body: msg.Data,
683 }
684
685 if msg.Header != nil {
686 dm.Metadata = map[string]string{}
687 for k, v := range msg.Header {
688 var sv string
689 if len(v) > 0 {
690 sv = v[0]
691 }
692 kb, err := url.QueryUnescape(k)
693 if err != nil {
694 return nil, err
695 }
696 vb, err := url.QueryUnescape(sv)
697 if err != nil {
698 return nil, err
699 }
700 dm.Metadata[kb] = vb
701 }
702 }
703 return &dm, nil
704 }