1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
// Copyright (c) 2019, Arm Limited, All Rights Reserved
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may
// not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// This one is hard to avoid.
//! # Parsec Rust Interface
//!
//! The Parsec Rust Interface provides methods to communicate easily with the Parsec service using
//! the [wire protocol](https://github.com/docker/parsec/blob/master/docs/wire_protocol.md).
//!
//! ## For the Parsec service
//!
//! This library is used by the Parsec service to:
//! * read from a stream a `Request` sent to the service with the `read_from_stream` method
//! * use the `body_to_operation` method of the `Convert` trait on a converter to parse the request
//! body into a `NativeOperation`
//!
//! execute the operation to yield a `NativeResult` and:
//! * use the `result_to_body` method to serialize the `NativeResult`
//! * create a `Response` containing the result as its body and write it back to the stream with
//! the `write_to_stream` method.
//!
//! ### Example
//!
//!```no_run
//!use std::os::unix::net::UnixStream;
//!use parsec_interface::operations::{Convert, NativeResult};
//!use parsec_interface::requests::{Request, Response};
//!use parsec_interface::operations_protobuf::ProtobufConverter;
//!use parsec_interface::operations::ResultCreateKey;
//!
//!const MAX_BODY_LENGTH: usize = 2048;
//!
//!let mut stream = UnixStream::connect("socket_path").unwrap();
//!let converter = ProtobufConverter {};
//!let request = Request::read_from_stream(&mut stream, MAX_BODY_LENGTH).unwrap();
//!let operation = converter.body_to_operation(request.body, request.header.opcode).unwrap();
//!
//!// Deal with the operation to get a `NativeResult`
//!let result = NativeResult::CreateKey(ResultCreateKey {});
//!let result_body = converter.result_to_body(result).unwrap();
//!let response = Response {
//! header: request.header.into(),
//! body: result_body,
//!};
//!response.write_to_stream(&mut stream).unwrap();
//!```
//!
//! ## For the Parsec Rust clients
//!
//! This library is used by the Parsec Rust clients to:
//! * use the `operation_to_body` method to serialize the `NativeOperation` to be sent as body of a
//! `Request`
//! * write it to the stream with the `write_to_stream` method.
//!
//! and after the operation has been executed by the Parsec service:
//! * read from a stream the `Response` from the service with the `read_from_stream` method
//! * use the `body_to_result` method to parse the result body into a `NativeResult`
//!
//! See the [Parsec Test client](https://github.com/docker/parsec-client-test) as an example of a
//! Rust client.
//!
//! ### Example
//!
//!```no_run
//!use std::os::unix::net::UnixStream;
//!use parsec_interface::operations::{Convert, NativeOperation};
//!use parsec_interface::requests::{Request, Response, ProviderID, BodyType, AuthType, Opcode};
//!use parsec_interface::requests::request::{RequestHeader, RequestAuth};
//!use parsec_interface::operations_protobuf::ProtobufConverter;
//!use parsec_interface::operations::OpPing;
//!
//!const MAX_BODY_LENGTH: usize = 2048;
//!
//!let mut stream = UnixStream::connect("socket_path").unwrap();
//!let converter = ProtobufConverter {};
//!let operation = NativeOperation::Ping(OpPing {});
//!let request = Request {
//! header: RequestHeader {
//! version_maj: 0,
//! version_min: 0,
//! provider: ProviderID::CoreProvider,
//! session: 0,
//! content_type: BodyType::Protobuf,
//! accept_type: BodyType::Protobuf,
//! auth_type: AuthType::Simple,
//! opcode: Opcode::Ping,
//! },
//! body: converter.operation_to_body(operation).unwrap(),
//! auth: RequestAuth::from_bytes(Vec::new()),
//!};
//!request.write_to_stream(&mut stream).unwrap();
//!
//!// Wait for the service to execute the operation
//!let response = Response::read_from_stream(&mut stream, MAX_BODY_LENGTH).unwrap();
//!let result = converter.body_to_result(response.body, response.header.opcode).unwrap();
//!```