1// Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
2// Licensed under the MIT License:
3//
4// Permission is hereby granted, free of charge, to any person obtaining a copy
5// of this software and associated documentation files (the "Software"), to deal
6// in the Software without restriction, including without limitation the rights
7// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8// copies of the Software, and to permit persons to whom the Software is
9// furnished to do so, subject to the following conditions:
10//
11// The above copyright notice and this permission notice shall be included in
12// all copies or substantial portions of the Software.
13//
14// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20// THE SOFTWARE.
21
22#pragma once
23
24#if defined(__GNUC__) && !defined(CAPNP_HEADER_WARNINGS)
25#pragma GCC system_header
26#endif
27
28#include "schema.h"
29#include <kj/memory.h>
30#include <kj/mutex.h>
31
32namespace capnp {
33
34class SchemaLoader {
35 // Class which can be used to construct Schema objects from schema::Nodes as defined in
36 // schema.capnp.
37 //
38 // It is a bad idea to use this class on untrusted input with exceptions disabled -- you may
39 // be exposing yourself to denial-of-service attacks, as attackers can easily construct schemas
40 // that are subtly inconsistent in a way that causes exceptions to be thrown either by
41 // SchemaLoader or by the dynamic API when the schemas are subsequently used. If you enable and
42 // properly catch exceptions, you should be OK -- assuming no bugs in the Cap'n Proto
43 // implementation, of course.
44
45public:
46 class LazyLoadCallback {
47 public:
48 virtual void load(const SchemaLoader& loader, uint64_t id) const = 0;
49 // Request that the schema node with the given ID be loaded into the given SchemaLoader. If
50 // the callback is able to find a schema for this ID, it should invoke `loadOnce()` on
51 // `loader` to load it. If no such node exists, it should simply do nothing and return.
52 //
53 // The callback is allowed to load schema nodes other than the one requested, e.g. because it
54 // expects they will be needed soon.
55 //
56 // If the `SchemaLoader` is used from multiple threads, the callback must be thread-safe.
57 // In particular, it's possible for multiple threads to invoke `load()` with the same ID.
58 // If the callback performs a large amount of work to look up IDs, it should be sure to
59 // de-dup these requests.
60 };
61
62 SchemaLoader();
63
64 SchemaLoader(const LazyLoadCallback& callback);
65 // Construct a SchemaLoader which will invoke the given callback when a schema node is requested
66 // that isn't already loaded.
67
68 ~SchemaLoader() noexcept(false);
69 KJ_DISALLOW_COPY(SchemaLoader);
70
71 Schema get(uint64_t id, schema::Brand::Reader brand = schema::Brand::Reader(),
72 Schema scope = Schema()) const;
73 // Gets the schema for the given ID, throwing an exception if it isn't present.
74 //
75 // The returned schema may be invalidated if load() is called with a new schema for the same ID.
76 // In general, you should not call load() while a schema from this loader is in-use.
77 //
78 // `brand` and `scope` are used to determine brand bindings where relevant. `brand` gives
79 // parameter bindings for the target type's brand parameters that were specified at the reference
80 // site. `scope` specifies the scope in which the type ID appeared -- if `brand` itself contains
81 // parameter references or indicates that some parameters will be inherited, these will be
82 // interpreted within / inherited from `scope`.
83
84 kj::Maybe<Schema> tryGet(uint64_t id, schema::Brand::Reader bindings = schema::Brand::Reader(),
85 Schema scope = Schema()) const;
86 // Like get() but doesn't throw.
87
88 Schema getUnbound(uint64_t id) const;
89 // Gets a special version of the schema in which all brand parameters are "unbound". This means
90 // that if you look up a type via the Schema API, and it resolves to a brand parameter, the
91 // returned Type's getBrandParameter() method will return info about that parameter. Otherwise,
92 // normally, all brand parameters that aren't otherwise bound are assumed to simply be
93 // "AnyPointer".
94
95 Type getType(schema::Type::Reader type, Schema scope = Schema()) const;
96 // Convenience method which interprets a schema::Type to produce a Type object. Implemented in
97 // terms of get().
98
99 Schema load(const schema::Node::Reader& reader);
100 // Loads the given schema node. Validates the node and throws an exception if invalid. This
101 // makes a copy of the schema, so the object passed in can be destroyed after this returns.
102 //
103 // If the node has any dependencies which are not already loaded, they will be initialized as
104 // stubs -- empty schemas of whichever kind is expected.
105 //
106 // If another schema for the given reader has already been seen, the loader will inspect both
107 // schemas to determine which one is newer, and use that that one. If the two versions are
108 // found to be incompatible, an exception is thrown. If the two versions differ but are
109 // compatible and the loader cannot determine which is newer (e.g., the only changes are renames),
110 // the existing schema will be preferred. Note that in any case, the loader will end up keeping
111 // around copies of both schemas, so you shouldn't repeatedly reload schemas into the same loader.
112 //
113 // The following properties of the schema node are validated:
114 // - Struct size and preferred list encoding are valid and consistent.
115 // - Struct members are fields or unions.
116 // - Union members are fields.
117 // - Field offsets are in-bounds.
118 // - Ordinals and codeOrders are sequential starting from zero.
119 // - Values are of the right union case to match their types.
120 //
121 // You should assume anything not listed above is NOT validated. In particular, things that are
122 // not validated now, but could be in the future, include but are not limited to:
123 // - Names.
124 // - Annotation values. (This is hard because the annotation declaration is not always
125 // available.)
126 // - Content of default/constant values of pointer type. (Validating these would require knowing
127 // their schema, but even if the schemas are available at validation time, they could be
128 // updated by a subsequent load(), invalidating existing values. Instead, these values are
129 // validated at the time they are used, as usual for Cap'n Proto objects.)
130 //
131 // Also note that unknown types are not considered invalid. Instead, the dynamic API returns
132 // a DynamicValue with type UNKNOWN for these.
133
134 Schema loadOnce(const schema::Node::Reader& reader) const;
135 // Like `load()` but does nothing if a schema with the same ID is already loaded. In contrast,
136 // `load()` would attempt to compare the schemas and take the newer one. `loadOnce()` is safe
137 // to call even while concurrently using schemas from this loader. It should be considered an
138 // error to call `loadOnce()` with two non-identical schemas that share the same ID, although
139 // this error may or may not actually be detected by the implementation.
140
141 template <typename T>
142 void loadCompiledTypeAndDependencies();
143 // Load the schema for the given compiled-in type and all of its dependencies.
144 //
145 // If you want to be able to cast a DynamicValue built from this SchemaLoader to the compiled-in
146 // type using as<T>(), you must call this method before constructing the DynamicValue. Otherwise,
147 // as<T>() will throw an exception complaining about type mismatch.
148
149 kj::Array<Schema> getAllLoaded() const;
150 // Get a complete list of all loaded schema nodes. It is particularly useful to call this after
151 // loadCompiledTypeAndDependencies<T>() in order to get a flat list of all of T's transitive
152 // dependencies.
153
154private:
155 class Validator;
156 class CompatibilityChecker;
157 class Impl;
158 class InitializerImpl;
159 class BrandedInitializerImpl;
160 kj::MutexGuarded<kj::Own<Impl>> impl;
161
162 void loadNative(const _::RawSchema* nativeSchema);
163};
164
165template <typename T>
166inline void SchemaLoader::loadCompiledTypeAndDependencies() {
167 loadNative(&_::rawSchema<T>());
168}
169
170} // namespace capnp
171