Current section
Files
Jump to
Current section
Files
src/integrations/openapi/adk_openapi_toolset.erl
%% @doc Immutable OpenAPI 3.0/3.1 toolset compiler and bounded executor.
%%
%% Supported documents are OpenAPI `3.0.x' and `3.1.x'. Supported security is
%% `apiKey' in header or query, HTTP `bearer', and OAuth 2.0 (implicit,
%% password, client-credentials, or authorization-code flows); OAuth token
%% acquisition remains the injected auth manager's responsibility. Cookie API
%% keys, HTTP Basic/Digest, mutual TLS, and OpenID Connect are not accepted.
%%
%% The request subset is path/query/header parameters using OpenAPI simple or
%% form serialization, JSON request bodies, and JSON responses. Multipart,
%% form-urlencoded, cookie parameters, callbacks, and remote `$ref' values are
%% intentionally rejected rather than silently weakened.
%%
%% The compiler accepts an already-decoded JSON map, resolves only local
%% references, and emits deterministic `adk_tool' schema maps. Network and
%% credential access are injected behaviours. Credentials are resolved only in
%% the short-lived execution worker and are never accepted as tool arguments or
%% copied from the agent context.
-module(adk_openapi_toolset).
-export([compile/2, capabilities/0, schemas/1, schema/2,
execute/3, execute/4, resolved_call/4]).
-record(toolset, {
operations = #{} :: map(),
schemas = [] :: [map()],
transport :: {module(), adk_openapi_http_transport:handle()},
auth = undefined :: undefined |
{module(), adk_openapi_auth_manager:handle()},
policy = #{} :: map()
}).
-opaque toolset() :: #toolset{}.
-export_type([toolset/0]).
-define(DEFAULT_TIMEOUT_MS, 10000).
-define(DEFAULT_MAX_REQUEST_BYTES, 1048576).
-define(DEFAULT_MAX_RESPONSE_BYTES, 4194304).
-define(DEFAULT_MAX_SPEC_BYTES, 2097152).
-define(DEFAULT_MAX_OPERATIONS, 100).
-define(DEFAULT_MAX_PARAMETERS, 64).
-define(DEFAULT_MAX_RESPONSES, 32).
-define(DEFAULT_MAX_SCHEMA_DEPTH, 32).
-define(EXECUTION_MAX_HEAP_WORDS, 4000000).
-define(EXECUTION_MAX_RESULT_BYTES, 16777216).
-define(EXECUTION_WATCHDOG_MAX_HEAP_WORDS, 8192).
-spec capabilities() -> map().
capabilities() ->
#{openapi_versions => [<<"3.0">>, <<"3.1">>],
references => local_only,
parameter_locations => [path, query, header],
request_media_types => [<<"application/json">>,
<<"application/*+json">>],
security => [api_key, http_bearer, oauth2],
security_details => #{api_key_locations => [header, query],
http_schemes => [bearer],
oauth2_flows => [implicit, password,
client_credentials,
authorization_code]},
execution => #{bounded_worker => true,
redirects => disabled,
host_allowlist => required,
response_stream_limit_required => true},
tool_schema => adk_tool_compatible}.
%% @doc Compile a strict OpenAPI document. Required options are:
%% `transport => {Module, OpaqueHandle}' and a non-empty `allowed_hosts' list.
%% `base_url' is required only when the document has no usable server URL.
-spec compile(map(), map()) -> {ok, toolset()} | {error, term()}.
compile(Spec, Opts) when is_map(Spec), is_map(Opts) ->
case normalize_options(Opts) of
{ok, Policy, Transport, Auth} ->
case validate_spec_boundary(Spec, Policy) of
ok -> compile_spec(Spec, Policy, Transport, Auth);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
compile(_Spec, _Opts) ->
{error, invalid_openapi_document}.
-spec schemas(toolset()) -> [map()].
schemas(#toolset{schemas = Schemas}) -> Schemas.
-spec schema(toolset(), binary()) -> {ok, map()} | {error, unknown_tool}.
schema(#toolset{operations = Operations}, Name) when is_binary(Name) ->
case maps:find(Name, Operations) of
{ok, Operation} -> {ok, maps:get(tool_schema, Operation)};
error -> {error, unknown_tool}
end;
schema(_Toolset, _Name) ->
{error, unknown_tool}.
-spec execute(toolset(), binary(), map()) -> {ok, map()} | {error, term()}.
execute(Toolset, Name, Args) ->
execute(Toolset, Name, Args, #{}).
%% @doc Execute one operation. Context is deliberately not forwarded to the
%% auth manager or transport; this prevents session credentials from becoming
%% network metadata by accident.
-spec execute(toolset(), binary(), map(), map()) ->
{ok, map()} | {error, term()}.
execute(Toolset = #toolset{operations = Operations,
policy = Policy}, Name, Args, Context)
when is_binary(Name), is_map(Args), is_map(Context) ->
case maps:find(Name, Operations) of
{ok, Operation} ->
Timeout = maps:get(timeout_ms, Policy),
run_bounded(Toolset, Operation, Args, Timeout);
error -> {error, unknown_tool}
end;
execute(_Toolset, _Name, _Args, _Context) ->
{error, invalid_openapi_execution}.
%% @doc Build an `adk_tool_executor' compatible resolved call without exposing
%% the toolset's transport/auth handles to model-visible arguments.
-spec resolved_call(toolset(), binary(), map(), map()) ->
{ok, map()} | {error, term()}.
resolved_call(Toolset = #toolset{operations = Operations}, Name, Args, _Context)
when is_binary(Name), is_map(Args), is_map(_Context) ->
case maps:find(Name, Operations) of
{ok, Operation} ->
{ok, #{name => Name,
args => Args,
execute => fun() -> execute(Toolset, Name, Args, #{}) end,
parallel_safe => maps:get(parallel_safe, Operation),
pause_capable => false}};
error -> {error, unknown_tool}
end;
resolved_call(_Toolset, _Name, _Args, _Context) ->
{error, invalid_openapi_execution}.
normalize_options(Opts) ->
case validate_ref(transport, maps:get(transport, Opts, undefined)) of
{ok, Transport} ->
case validate_optional_ref(auth, maps:get(auth, Opts, undefined)) of
{ok, Auth} -> normalize_policy(Opts, Transport, Auth);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end.
normalize_policy(Opts, Transport, Auth) ->
case allowed_schemes(maps:get(allowed_schemes, Opts, [<<"https">>])) of
{ok, Schemes} ->
AllowPrivate = maps:get(allow_private_hosts, Opts, false),
case is_boolean(AllowPrivate) of
false -> {error, {invalid_openapi_option, allow_private_hosts}};
true ->
case allowed_hosts(maps:get(allowed_hosts, Opts, undefined),
AllowPrivate) of
{ok, Hosts} ->
normalize_limits(Opts, Transport, Auth, Schemes,
Hosts, AllowPrivate);
{error, _} = Error -> Error
end
end;
{error, _} = Error -> Error
end.
normalize_limits(Opts, Transport, Auth, Schemes, Hosts, AllowPrivate) ->
LimitDefs = [
{timeout_ms, ?DEFAULT_TIMEOUT_MS},
{max_request_body_bytes, ?DEFAULT_MAX_REQUEST_BYTES},
{max_response_bytes, ?DEFAULT_MAX_RESPONSE_BYTES},
{max_spec_bytes, ?DEFAULT_MAX_SPEC_BYTES},
{max_operations, ?DEFAULT_MAX_OPERATIONS},
{max_parameters, ?DEFAULT_MAX_PARAMETERS},
{max_responses, ?DEFAULT_MAX_RESPONSES},
{max_schema_depth, ?DEFAULT_MAX_SCHEMA_DEPTH}
],
case positive_limits(LimitDefs, Opts, #{}) of
{ok, Limits} ->
BaseUrl = maps:get(base_url, Opts, undefined),
case optional_binary(base_url, BaseUrl) of
{ok, NormalizedBase} ->
Policy0 = Limits#{allowed_schemes => Schemes,
allowed_hosts => Hosts,
allow_private_hosts => AllowPrivate,
base_url => NormalizedBase,
follow_redirects => false},
case validate_configured_base_url(Policy0) of
{ok, Policy} ->
{ok, Policy, Transport, Auth};
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end.
validate_ref(_Key, {Module, Handle})
when is_atom(Module),
(is_pid(Handle) orelse is_atom(Handle) orelse is_reference(Handle)) ->
{ok, {Module, Handle}};
validate_ref(Key, _Invalid) ->
{error, {invalid_openapi_option, Key}}.
validate_optional_ref(_Key, undefined) -> {ok, undefined};
validate_optional_ref(Key, Value) -> validate_ref(Key, Value).
positive_limits([], _Opts, Acc) -> {ok, Acc};
positive_limits([{Key, Default} | Rest], Opts, Acc) ->
case maps:get(Key, Opts, Default) of
Value when is_integer(Value), Value > 0 ->
positive_limits(Rest, Opts, Acc#{Key => Value});
_ -> {error, {invalid_openapi_option, Key}}
end.
optional_binary(_Key, undefined) -> {ok, undefined};
optional_binary(_Key, Value) when is_binary(Value), byte_size(Value) > 0 ->
{ok, Value};
optional_binary(Key, _Value) -> {error, {invalid_openapi_option, Key}}.
allowed_schemes(Values) when is_list(Values), Values =/= [] ->
Normalized = lists:usort([lower_binary(Value) || Value <- Values,
is_binary(Value)]),
case length(Normalized) =:= length(Values) andalso
lists:all(fun(Scheme) ->
Scheme =:= <<"https">> orelse Scheme =:= <<"http">>
end, Normalized) of
true -> {ok, Normalized};
false -> {error, {invalid_openapi_option, allowed_schemes}}
end;
allowed_schemes(_) ->
{error, {invalid_openapi_option, allowed_schemes}}.
allowed_hosts(Values, AllowPrivate) when is_list(Values), Values =/= [] ->
normalize_allowed_hosts(Values, AllowPrivate, []);
allowed_hosts(_Values, _AllowPrivate) ->
{error, {invalid_openapi_option, allowed_hosts}}.
normalize_allowed_hosts([], _AllowPrivate, Acc) ->
{ok, lists:usort(Acc)};
normalize_allowed_hosts([Host | Rest], AllowPrivate, Acc)
when is_binary(Host) ->
case canonical_host(Host) of
{ok, Canonical} ->
case private_host(Canonical) andalso not AllowPrivate of
true -> {error, private_host_not_allowed};
false -> normalize_allowed_hosts(Rest, AllowPrivate,
[Canonical | Acc])
end;
error -> {error, {invalid_openapi_option, allowed_hosts}}
end;
normalize_allowed_hosts(_Values, _AllowPrivate, _Acc) ->
{error, {invalid_openapi_option, allowed_hosts}}.
validate_configured_base_url(#{base_url := undefined} = Policy) ->
{ok, Policy};
validate_configured_base_url(#{base_url := Url} = Policy) ->
case validate_base_url(Url, Policy) of
{ok, Normalized} -> {ok, Policy#{base_url => Normalized}};
{error, _} = Error -> Error
end.
validate_spec_boundary(Spec, Policy) ->
MaxDepth = maps:get(max_schema_depth, Policy) * 4,
case adk_openapi_schema:validate_json(Spec, MaxDepth) of
ok ->
try jsx:encode(Spec) of
Encoded ->
case byte_size(Encoded) =<
maps:get(max_spec_bytes, Policy) of
true ->
adk_openapi_schema:reject_remote_refs(
Spec, MaxDepth);
false -> {error, openapi_document_too_large}
end
catch
_:_ -> {error, invalid_openapi_document}
end;
{error, _} -> {error, invalid_openapi_document}
end.
compile_spec(Spec, Policy, Transport, Auth) ->
case openapi_version(Spec) of
{ok, Version} ->
case compile_security_schemes(Spec, Policy) of
{ok, SecuritySchemes} ->
case compile_security(
maps:get(<<"security">>, Spec, []),
SecuritySchemes) of
{ok, RootSecurity} ->
case root_paths(Spec) of
{ok, Paths} ->
compile_paths(
lists:sort(maps:to_list(Paths)),
Spec, Version, SecuritySchemes,
RootSecurity, Policy, #{}, [] ,0,
Transport, Auth);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end.
openapi_version(#{<<"openapi">> := Version}) when is_binary(Version) ->
%% The OpenAPI field is a semantic version, not a prefix. Accept only
%% released numeric 3.0.x/3.1.x versions so values such as `3.1.latest'
%% cannot silently select a different parser contract.
case re:run(Version,
<<"^3\\.(0|1)\\.(0|[1-9][0-9]*)$">>,
[{capture, [1], binary}]) of
{match, [<<"0">>]} -> {ok, openapi_3_0};
{match, [<<"1">>]} -> {ok, openapi_3_1};
nomatch -> {error, unsupported_openapi_version}
end;
openapi_version(_) -> {error, invalid_openapi_version}.
root_paths(#{<<"paths">> := Paths}) when is_map(Paths), map_size(Paths) > 0 ->
{ok, Paths};
root_paths(_) -> {error, invalid_openapi_paths}.
compile_paths([], _Spec, _Version, _Schemes, _RootSecurity, Policy,
Operations, Schemas, Count, Transport, Auth) ->
case Count > 0 of
true ->
SortedSchemas = lists:sort(
fun(A, B) ->
maps:get(<<"name">>, A) <
maps:get(<<"name">>, B)
end, Schemas),
{ok, #toolset{operations = Operations,
schemas = SortedSchemas,
transport = Transport,
auth = Auth,
policy = Policy}};
false -> {error, openapi_has_no_operations}
end;
compile_paths([{Path, PathItem0} | Rest], Spec, Version, Schemes,
RootSecurity, Policy, Operations, Schemas, Count,
Transport, Auth) ->
case extension_key(Path) of
true ->
compile_paths(Rest, Spec, Version, Schemes, RootSecurity,
Policy, Operations, Schemas, Count,
Transport, Auth);
false -> compile_path_entry(
Path, PathItem0, Rest, Spec, Version, Schemes,
RootSecurity, Policy, Operations, Schemas, Count,
Transport, Auth)
end.
compile_path_entry(Path, PathItem0, Rest, Spec, Version, Schemes,
RootSecurity, Policy, Operations, Schemas, Count,
Transport, Auth) ->
case valid_path_template(Path) of
false -> {error, invalid_openapi_path};
true ->
case adk_openapi_schema:resolve_object(Spec, PathItem0, Policy) of
{ok, PathItem} ->
case validate_path_item_keys(PathItem) of
ok ->
case compile_parameter_list(
maps:get(<<"parameters">>, PathItem, []),
Spec, Policy) of
{ok, PathParameters} ->
case compile_path_operations(
method_keys(), Path, PathItem,
PathParameters, Spec, Version,
Schemes, RootSecurity, Policy,
Operations, Schemas, Count) of
{ok, Ops1, Schemas1, Count1} ->
compile_paths(
Rest, Spec, Version, Schemes,
RootSecurity, Policy, Ops1,
Schemas1, Count1,
Transport, Auth);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} -> {error, invalid_openapi_path_item}
end
end.
compile_path_operations([], _Path, _PathItem, _PathParameters, _Spec,
_Version, _Schemes, _RootSecurity, _Policy,
Operations, Schemas, Count) ->
{ok, Operations, Schemas, Count};
compile_path_operations([{MethodKey, Method} | Rest], Path, PathItem,
PathParameters, Spec, Version, Schemes,
RootSecurity, Policy, Operations, Schemas, Count) ->
case maps:find(MethodKey, PathItem) of
error ->
compile_path_operations(Rest, Path, PathItem, PathParameters,
Spec, Version, Schemes, RootSecurity,
Policy, Operations, Schemas, Count);
{ok, Operation0} when is_map(Operation0) ->
case Count < maps:get(max_operations, Policy) of
false -> {error, too_many_openapi_operations};
true ->
case compile_operation(
Method, Path, PathItem, PathParameters,
Operation0, Spec, Version, Schemes,
RootSecurity, Policy) of
{ok, Name, Operation, ToolSchema} ->
case maps:is_key(Name, Operations) of
true -> {error, duplicate_operation_id};
false ->
compile_path_operations(
Rest, Path, PathItem, PathParameters,
Spec, Version, Schemes, RootSecurity,
Policy, Operations#{Name => Operation},
[ToolSchema | Schemas], Count + 1)
end;
{error, _} = Error -> Error
end
end;
{ok, _} -> {error, invalid_openapi_operation}
end.
compile_operation(Method, Path, PathItem, PathParameters, Operation,
Spec, _Version, Schemes, RootSecurity, Policy) ->
case validate_operation_keys(Operation) of
ok ->
case operation_id(Operation) of
{ok, Name} ->
case compile_parameter_list(
maps:get(<<"parameters">>, Operation, []),
Spec, Policy) of
{ok, OperationParameters} ->
compile_operation_parts(
Name, Method, Path, PathItem,
merge_parameters(PathParameters,
OperationParameters),
Operation, Spec, Schemes, RootSecurity,
Policy);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end.
compile_operation_parts(Name, Method, Path, PathItem, ParametersResult,
Operation, Spec, Schemes, RootSecurity, Policy) ->
case ParametersResult of
{ok, Parameters} ->
case length(Parameters) =< maps:get(max_parameters, Policy) of
false -> {error, too_many_openapi_parameters};
true ->
case validate_path_parameters(Path, Parameters) of
ok ->
SecurityValue = maps:get(
<<"security">>, Operation,
inherited),
case operation_security(SecurityValue,
RootSecurity, Schemes) of
{ok, Security} ->
compile_body_responses_server(
Name, Method, Path, PathItem,
Parameters, Operation, Spec, Security,
Policy);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end
end;
{error, _} = Error -> Error
end.
compile_body_responses_server(Name, Method, Path, PathItem, Parameters,
Operation, Spec, Security, Policy) ->
case security_parameter_conflicts(Security, Parameters) of
[] ->
case compile_request_body(Operation, Spec, Policy, Parameters) of
{ok, Body} ->
case compile_responses(Operation, Spec, Policy) of
{ok, Responses} ->
case operation_base_url(
Operation, PathItem, Spec, Policy) of
{ok, BaseUrl} ->
finish_operation(
Name, Method, Path, Parameters, Body,
Responses, Security, BaseUrl,
Operation, Policy);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
_ -> {error, security_parameter_conflict}
end.
finish_operation(Name, Method, Path, Parameters, Body, Responses,
Security, BaseUrl, Operation, Policy) ->
case build_tool_schema(Name, Parameters, Body, Operation) of
{ok, ToolSchema, InputSchema} ->
ParallelSafe = Method =:= <<"GET">> orelse
Method =:= <<"HEAD">>,
Compiled = #{name => Name,
method => Method,
path => Path,
parameters => Parameters,
body => Body,
responses => Responses,
security => Security,
base_url => BaseUrl,
input_schema => InputSchema,
tool_schema => ToolSchema,
parallel_safe => ParallelSafe,
policy => maps:with(
[timeout_ms, max_request_body_bytes,
max_response_bytes, allowed_schemes,
allowed_hosts, allow_private_hosts,
follow_redirects], Policy)},
{ok, Name, Compiled, ToolSchema};
{error, _} = Error -> Error
end.
method_keys() ->
[{<<"get">>, <<"GET">>}, {<<"put">>, <<"PUT">>},
{<<"post">>, <<"POST">>}, {<<"delete">>, <<"DELETE">>},
{<<"options">>, <<"OPTIONS">>}, {<<"head">>, <<"HEAD">>},
{<<"patch">>, <<"PATCH">>}].
validate_path_item_keys(PathItem) ->
Allowed = [Key || {Key, _} <- method_keys()] ++
[<<"parameters">>, <<"summary">>, <<"description">>,
<<"servers">>, <<"trace">>],
case validate_keys(PathItem, Allowed, invalid_openapi_path_item_key) of
ok ->
%% TRACE commonly reflects request headers and therefore must not
%% receive an out-of-band bearer/API key from an agent tool.
case maps:is_key(<<"trace">>, PathItem) of
true -> {error, unsupported_openapi_method};
false ->
valid_optional_binaries(
PathItem, [<<"summary">>, <<"description">>],
invalid_openapi_path_item)
end;
{error, _} = Error -> Error
end.
validate_operation_keys(Operation) ->
Allowed = [<<"operationId">>, <<"summary">>, <<"description">>,
<<"parameters">>, <<"requestBody">>, <<"responses">>,
<<"security">>, <<"servers">>, <<"tags">>,
<<"deprecated">>, <<"externalDocs">>],
case validate_keys(Operation, Allowed, invalid_openapi_operation_key) of
ok -> validate_operation_annotations(Operation);
{error, _} = Error -> Error
end.
validate_operation_annotations(Operation) ->
case valid_optional_binaries(
Operation, [<<"summary">>, <<"description">>],
invalid_openapi_operation) of
ok ->
Tags = maps:get(<<"tags">>, Operation, []),
Deprecated = maps:get(<<"deprecated">>, Operation, false),
ExternalDocs = maps:get(<<"externalDocs">>, Operation, #{}),
case is_list(Tags) andalso lists:all(fun is_binary/1, Tags) andalso
is_boolean(Deprecated) andalso is_map(ExternalDocs) of
true -> ok;
false -> {error, invalid_openapi_operation}
end;
{error, _} = Error -> Error
end.
valid_optional_binaries(_Map, [], _Error) -> ok;
valid_optional_binaries(Map, [Key | Rest], Error) ->
case maps:find(Key, Map) of
error -> valid_optional_binaries(Map, Rest, Error);
{ok, Value} when is_binary(Value) ->
valid_optional_binaries(Map, Rest, Error);
{ok, _} -> {error, Error}
end.
validate_keys(Map, Allowed, Error) ->
Unknown = [Key || Key <- maps:keys(Map),
not lists:member(Key, Allowed),
not extension_key(Key)],
case Unknown of [] -> ok; _ -> {error, Error} end.
extension_key(<<"x-", _/binary>>) -> true;
extension_key(_) -> false.
operation_id(#{<<"operationId">> := Name}) when is_binary(Name) ->
case byte_size(Name) =< 64 andalso
re:run(Name, <<"^[A-Za-z_][A-Za-z0-9_.-]*$">>,
[{capture, none}]) =:= match of
true -> {ok, Name};
false -> {error, invalid_operation_id}
end;
operation_id(_) -> {error, missing_operation_id}.
compile_parameter_list([], _Spec, _Policy) -> {ok, []};
compile_parameter_list(List, Spec, Policy) when is_list(List) ->
compile_parameters(List, Spec, Policy, #{}, []);
compile_parameter_list(_List, _Spec, _Policy) ->
{error, invalid_openapi_parameters}.
compile_parameters([], _Spec, _Policy, _Seen, Acc) ->
{ok, lists:reverse(Acc)};
compile_parameters([Parameter0 | Rest], Spec, Policy, Seen, Acc) ->
case adk_openapi_schema:resolve_object(Spec, Parameter0, Policy) of
{ok, Parameter} ->
case compile_parameter(Parameter, Spec, Policy) of
{ok, Descriptor} ->
Key = parameter_identity(Descriptor),
case maps:is_key(Key, Seen) of
true -> {error, duplicate_openapi_parameter};
false ->
compile_parameters(
Rest, Spec, Policy, Seen#{Key => true},
[Descriptor | Acc])
end;
{error, _} = Error -> Error
end;
{error, _} -> {error, invalid_openapi_parameter}
end.
compile_parameter(Parameter, Spec, Policy) ->
case {maps:find(<<"name">>, Parameter),
maps:find(<<"in">>, Parameter),
maps:find(<<"schema">>, Parameter)} of
{{ok, Name}, {ok, LocationBin}, {ok, RawSchema}}
when is_binary(Name), byte_size(Name) > 0,
is_binary(LocationBin) ->
case parameter_location(LocationBin) of
{ok, Location} ->
compile_parameter_schema(Parameter, Name, Location,
RawSchema, Spec, Policy);
{error, _} = Error -> Error
end;
_ -> {error, invalid_openapi_parameter}
end.
compile_parameter_schema(Parameter, Name, Location, RawSchema,
Spec, Policy) ->
Required0 = maps:get(<<"required">>, Parameter, false),
Required = Location =:= path orelse Required0 =:= true,
case valid_parameter_flags(Parameter, Location, Required0) of
false -> {error, invalid_openapi_parameter};
true ->
case valid_parameter_name(Name, Location) of
false -> {error, unsafe_openapi_parameter};
true ->
case adk_openapi_schema:compile(
Spec, RawSchema, Policy) of
{ok, Schema} ->
case supported_parameter_schema(Schema) of
true ->
{Style, Explode} = parameter_encoding(
Parameter, Location),
{ok, #{name => Name,
request_name => request_name(
Name, Location),
location => Location,
required => Required,
schema => Schema,
style => Style,
explode => Explode}};
false ->
{error, unsupported_parameter_schema}
end;
{error, _} -> {error, invalid_parameter_schema}
end
end
end.
valid_parameter_flags(Parameter, path, Required0) ->
Required0 =:= true andalso valid_style(Parameter, path);
valid_parameter_flags(Parameter, Location, Required0) ->
is_boolean(Required0) andalso valid_style(Parameter, Location).
valid_style(Parameter, path) ->
maps:get(<<"style">>, Parameter, <<"simple">>) =:= <<"simple">> andalso
is_boolean(maps:get(<<"explode">>, Parameter, false));
valid_style(Parameter, query) ->
maps:get(<<"style">>, Parameter, <<"form">>) =:= <<"form">> andalso
is_boolean(maps:get(<<"explode">>, Parameter, true));
valid_style(Parameter, header) ->
maps:get(<<"style">>, Parameter, <<"simple">>) =:= <<"simple">> andalso
is_boolean(maps:get(<<"explode">>, Parameter, false)).
parameter_encoding(Parameter, path) ->
{simple, maps:get(<<"explode">>, Parameter, false)};
parameter_encoding(Parameter, query) ->
{form, maps:get(<<"explode">>, Parameter, true)};
parameter_encoding(Parameter, header) ->
{simple, maps:get(<<"explode">>, Parameter, false)}.
parameter_location(<<"path">>) -> {ok, path};
parameter_location(<<"query">>) -> {ok, query};
parameter_location(<<"header">>) -> {ok, header};
parameter_location(_) -> {error, unsupported_parameter_location}.
valid_parameter_name(<<"body">>, _Location) -> false;
valid_parameter_name(Name, header) ->
valid_header_name(Name) andalso not forbidden_header(Name) andalso
not credential_parameter_name(Name);
valid_parameter_name(Name, _Location) ->
valid_parameter_token(Name) andalso
not credential_parameter_name(Name).
%% Credentials declared by OpenAPI security schemes are resolved out of band
%% by the auth manager. Reject credential-looking ordinary parameters so a
%% model can never be invited to supply them as tool arguments. The shared
%% context guard intentionally does not classify generic keys; this extra
%% substring check covers common prefixed API-key headers such as X-API-Key.
credential_parameter_name(Name) ->
adk_context_guard:sensitive_key(Name) orelse
binary:match(normalized_parameter_name(Name), <<"apikey">>) =/= nomatch.
normalized_parameter_name(Name) ->
lists:foldl(
fun(Separator, Acc) ->
binary:replace(Acc, Separator, <<>>, [global])
end,
lower_binary(Name),
[<<"_">>, <<"-">>, <<" ">>, <<".">>, <<":">>]).
valid_security_parameter_name(Name, header) ->
valid_header_name(Name) andalso not forbidden_header(Name);
valid_security_parameter_name(Name, query) ->
valid_parameter_token(Name).
valid_parameter_token(Name) ->
byte_size(Name) =< 128 andalso
re:run(Name, <<"^[A-Za-z0-9_.-]+$">>, [{capture, none}]) =:= match.
valid_header_name(Name) ->
byte_size(Name) =< 128 andalso
re:run(Name, <<"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$">>,
[{capture, none}]) =:= match.
forbidden_header(Name) ->
lists:member(lower_binary(Name),
[<<"authorization">>, <<"proxy-authorization">>,
<<"cookie">>, <<"set-cookie">>, <<"host">>,
<<"content-type">>, <<"content-length">>,
<<"transfer-encoding">>,
<<"connection">>]).
request_name(Name, header) -> lower_binary(Name);
request_name(Name, _Location) -> Name.
supported_parameter_schema(true) -> false;
supported_parameter_schema(false) -> false;
supported_parameter_schema(Schema) when is_map(Schema) ->
case maps:get(<<"type">>, Schema, undefined) of
undefined -> false;
Type when Type =:= <<"string">>; Type =:= <<"integer">>;
Type =:= <<"number">>; Type =:= <<"boolean">> -> true;
Types when is_list(Types) ->
lists:all(fun primitive_or_null_type/1, Types);
<<"array">> ->
case maps:get(<<"items">>, Schema, undefined) of
Items when is_map(Items) -> supported_array_items(Items);
_ -> false
end;
_ -> false
end;
supported_parameter_schema(_) -> false.
primitive_or_null_type(Type) ->
lists:member(Type, [<<"string">>, <<"integer">>, <<"number">>,
<<"boolean">>, <<"null">>]).
supported_array_items(Items) ->
case maps:get(<<"type">>, Items, undefined) of
Type when Type =:= <<"string">>; Type =:= <<"integer">>;
Type =:= <<"number">>; Type =:= <<"boolean">> -> true;
_ -> false
end.
parameter_identity(#{location := header, request_name := Name}) ->
{header, Name};
parameter_identity(#{location := Location, name := Name}) ->
{Location, Name}.
merge_parameters(PathParameters, OperationParameters) ->
PathMap = maps:from_list([{parameter_identity(P), P}
|| P <- PathParameters]),
OperationMap = maps:from_list([{parameter_identity(P), P}
|| P <- OperationParameters]),
Merged = maps:merge(PathMap, OperationMap),
Parameters = [P || {_Key, P} <- lists:sort(maps:to_list(Merged))],
Names = [maps:get(name, P) || P <- Parameters],
case length(Names) =:= length(lists:usort(Names)) of
true -> {ok, Parameters};
false -> {error, ambiguous_parameter_name}
end.
validate_path_parameters(Path, Parameters) ->
Placeholders = path_placeholders(Path),
Declared = lists:sort([maps:get(name, P) || P <- Parameters,
maps:get(location, P) =:= path]),
case Placeholders of
{ok, Names} ->
case lists:sort(Names) =:= Declared of
true -> ok;
false -> {error, path_parameter_mismatch}
end;
_ -> {error, path_parameter_mismatch}
end.
path_placeholders(Path) ->
case re:run(Path, <<"\\{([^{}]+)\\}">>,
[global, {capture, [1], binary}]) of
nomatch -> {ok, []};
{match, Matches} ->
Names = [Name || [Name] <- Matches],
case length(Names) =:= length(lists:usort(Names)) andalso
lists:all(fun valid_parameter_token/1, Names) of
true -> {ok, Names};
false -> {error, invalid_path_template}
end
end.
valid_path_template(<<"/", _/binary>> = Path) ->
byte_size(Path) =< 2048 andalso
binary:match(Path, <<"?">>) =:= nomatch andalso
binary:match(Path, <<"#">>) =:= nomatch;
valid_path_template(_) -> false.
compile_request_body(Operation, Spec, Policy, Parameters) ->
case maps:find(<<"requestBody">>, Operation) of
error -> {ok, undefined};
{ok, Body0} ->
case length(Parameters) >= maps:get(max_parameters, Policy) of
true -> {error, too_many_openapi_parameters};
false ->
case adk_openapi_schema:resolve_object(
Spec, Body0, Policy) of
{ok, Body} ->
compile_request_body_object(Body, Spec, Policy);
{error, _} -> {error, invalid_request_body}
end
end
end.
compile_request_body_object(Body, Spec, Policy) ->
Required = maps:get(<<"required">>, Body, false),
Content = maps:get(<<"content">>, Body, undefined),
case is_boolean(Required) andalso is_map(Content) of
false -> {error, invalid_request_body};
true ->
case select_json_media(Content) of
{ok, MediaType, Media} when is_map(Media) ->
RawSchema = maps:get(<<"schema">>, Media, #{}),
case adk_openapi_schema:compile(
Spec, RawSchema, Policy) of
{ok, Schema} ->
{ok, #{required => Required,
media_type => MediaType,
schema => Schema}};
{error, _} -> {error, invalid_request_body_schema}
end;
error -> {error, unsupported_request_media_type}
end
end.
select_json_media(Content) ->
case maps:find(<<"application/json">>, Content) of
{ok, Media} -> {ok, <<"application/json">>, Media};
error ->
Candidates = lists:sort(
[{lower_binary(Type), Media}
|| {Type, Media} <- maps:to_list(Content),
is_binary(Type), json_media_type(Type)]),
case Candidates of
[{Type, Media} | _] -> {ok, Type, Media};
[] -> error
end
end.
json_media_type(Type0) ->
Type = lower_binary(hd(binary:split(Type0, <<";">>))),
Type =:= <<"application/json">> orelse
(binary:match(Type, <<"application/">>) =:= {0, 12} andalso
has_suffix(Type, <<"+json">>)).
compile_responses(Operation, Spec, Policy) ->
case maps:get(<<"responses">>, Operation, undefined) of
Responses when is_map(Responses), map_size(Responses) > 0 ->
case map_size(Responses) =< maps:get(max_responses, Policy) of
false -> {error, invalid_openapi_responses};
true ->
case compile_response_pairs(
lists:sort(maps:to_list(Responses)),
Spec, Policy, #{}) of
{ok, Compiled} ->
case has_success_response(maps:keys(Compiled)) of
true -> {ok, Compiled};
false -> {error, missing_success_response}
end;
{error, _} = Error -> Error
end
end;
_ -> {error, invalid_openapi_responses}
end.
compile_response_pairs([], _Spec, _Policy, Acc) -> {ok, Acc};
compile_response_pairs([{StatusKey, Response0} | Rest], Spec, Policy, Acc) ->
case valid_response_key(StatusKey) of
false -> {error, invalid_response_status};
true ->
case adk_openapi_schema:resolve_object(Spec, Response0, Policy) of
{ok, Response} ->
case compile_response(Response, Spec, Policy) of
{ok, Compiled} ->
compile_response_pairs(
Rest, Spec, Policy, Acc#{StatusKey => Compiled});
{error, _} = Error -> Error
end;
{error, _} -> {error, invalid_openapi_response}
end
end.
compile_response(#{<<"description">> := Description} = Response,
Spec, Policy) when is_binary(Description) ->
case maps:find(<<"content">>, Response) of
error -> {ok, #{media_type => undefined, schema => undefined}};
{ok, Content} when is_map(Content) ->
case select_json_media(Content) of
{ok, MediaType, Media} when is_map(Media) ->
RawSchema = maps:get(<<"schema">>, Media, #{}),
case adk_openapi_schema:compile(
Spec, RawSchema, Policy) of
{ok, Schema} ->
{ok, #{media_type => MediaType,
schema => Schema}};
{error, _} -> {error, invalid_response_schema}
end;
error ->
{ok, #{media_type => non_json, schema => undefined}}
end;
_ -> {error, invalid_openapi_response}
end;
compile_response(_Response, _Spec, _Policy) ->
{error, invalid_openapi_response}.
valid_response_key(<<A, B, C>>)
when A >= $1, A =< $5,
B >= $0, B =< $9, C >= $0, C =< $9 -> true;
valid_response_key(<<A, $X, $X>>) when A >= $1, A =< $5 -> true;
valid_response_key(<<"default">>) -> true;
valid_response_key(_) -> false.
has_success_response(Keys) ->
lists:any(fun(<<"2", _/binary>>) -> true;
(<<"default">>) -> true;
(_) -> false
end, Keys).
build_tool_schema(Name, Parameters, Body, Operation) ->
ParamProperties = maps:from_list(
[{maps:get(name, P), maps:get(schema, P)} || P <- Parameters]),
BodyProperties = case Body of
undefined -> #{};
_ -> #{<<"body">> => maps:get(schema, Body)}
end,
Properties = maps:merge(ParamProperties, BodyProperties),
ParamRequired = [maps:get(name, P) || P <- Parameters,
maps:get(required, P)],
Required = case Body of
#{required := true} -> ParamRequired ++ [<<"body">>];
_ -> ParamRequired
end,
InputSchema0 = #{<<"type">> => <<"object">>,
<<"properties">> => Properties,
<<"additionalProperties">> => false},
InputSchema = case Required of
[] -> InputSchema0;
_ -> InputSchema0#{<<"required">> => lists:sort(Required)}
end,
case adk_json_schema:compile(InputSchema) of
{ok, Checked} ->
Description = operation_description(Operation, Name),
ToolSchema = #{<<"name">> => Name,
<<"description">> => Description,
<<"parameters">> => Checked},
{ok, ToolSchema, Checked};
{error, _} -> {error, invalid_generated_tool_schema}
end.
operation_description(Operation, Name) ->
case maps:get(<<"description">>, Operation,
maps:get(<<"summary">>, Operation, Name)) of
Value when is_binary(Value), byte_size(Value) > 0 -> Value;
_ -> Name
end.
compile_security_schemes(Spec, Policy) ->
Components = maps:get(<<"components">>, Spec, #{}),
case Components of
Map when is_map(Map) ->
Schemes = maps:get(<<"securitySchemes">>, Map, #{}),
case is_map(Schemes) of
true -> compile_security_scheme_pairs(
lists:sort(maps:to_list(Schemes)),
Spec, Policy, #{});
false -> {error, invalid_security_schemes}
end;
_ -> {error, invalid_openapi_components}
end.
compile_security_scheme_pairs([], _Spec, _Policy, Acc) -> {ok, Acc};
compile_security_scheme_pairs([{Name, Scheme0} | Rest], Spec, Policy, Acc)
when is_binary(Name), byte_size(Name) > 0 ->
case adk_openapi_schema:resolve_object(Spec, Scheme0, Policy) of
{ok, Scheme} ->
case compile_security_scheme(Name, Scheme) of
{ok, Compiled} ->
compile_security_scheme_pairs(
Rest, Spec, Policy, Acc#{Name => Compiled});
{error, _} = Error -> Error
end;
{error, _} -> {error, invalid_security_scheme}
end;
compile_security_scheme_pairs(_Pairs, _Spec, _Policy, _Acc) ->
{error, invalid_security_scheme}.
compile_security_scheme(Name, #{<<"type">> := <<"apiKey">>,
<<"name">> := ParameterName,
<<"in">> := LocationBin})
when is_binary(ParameterName), byte_size(ParameterName) > 0 ->
case parameter_location(LocationBin) of
{ok, Location} when Location =:= header; Location =:= query ->
case valid_security_parameter_name(ParameterName, Location) of
true -> {ok, #{name => Name, type => api_key,
location => Location,
parameter_name => request_name(
ParameterName, Location)}};
false -> {error, unsafe_security_parameter}
end;
_ -> {error, unsupported_security_scheme}
end;
compile_security_scheme(Name, #{<<"type">> := <<"http">>,
<<"scheme">> := Scheme})
when is_binary(Scheme) ->
case lower_binary(Scheme) of
<<"bearer">> -> {ok, #{name => Name, type => bearer,
location => header,
parameter_name => <<"authorization">>}};
_ -> {error, unsupported_security_scheme}
end;
compile_security_scheme(Name, #{<<"type">> := <<"oauth2">>,
<<"flows">> := Flows})
when is_map(Flows), map_size(Flows) > 0 ->
case oauth_scopes(Flows) of
{ok, Scopes} ->
{ok, #{name => Name, type => oauth2,
location => header,
parameter_name => <<"authorization">>,
declared_scopes => Scopes}};
{error, _} = Error -> Error
end;
compile_security_scheme(_Name, _Scheme) ->
{error, unsupported_security_scheme}.
oauth_scopes(Flows) ->
Allowed = [<<"implicit">>, <<"password">>, <<"clientCredentials">>,
<<"authorizationCode">>],
case [Key || Key <- maps:keys(Flows), not lists:member(Key, Allowed)] of
[] -> oauth_flow_pairs(maps:to_list(Flows), []);
_ -> {error, unsupported_oauth_flow}
end.
oauth_flow_pairs([], Acc) -> {ok, lists:usort(Acc)};
oauth_flow_pairs([{_Name, Flow} | Rest], Acc) when is_map(Flow) ->
case maps:get(<<"scopes">>, Flow, undefined) of
Scopes when is_map(Scopes) ->
case lists:all(fun({Scope, Description}) ->
is_binary(Scope) andalso
is_binary(Description)
end, maps:to_list(Scopes)) of
true -> oauth_flow_pairs(Rest, maps:keys(Scopes) ++ Acc);
false -> {error, invalid_oauth_scopes}
end;
_ -> {error, invalid_oauth_flow}
end;
oauth_flow_pairs(_Flows, _Acc) -> {error, invalid_oauth_flow}.
operation_security(inherited, RootSecurity, _Schemes) ->
{ok, RootSecurity};
operation_security(Value, _RootSecurity, Schemes) ->
compile_security(Value, Schemes).
compile_security(Security, Schemes) when is_list(Security) ->
compile_security_requirements(Security, Schemes, []);
compile_security(_Security, _Schemes) ->
{error, invalid_security_requirement}.
compile_security_requirements([], _Schemes, Acc) ->
{ok, lists:reverse(Acc)};
compile_security_requirements([Requirement | Rest], Schemes, Acc)
when is_map(Requirement) ->
case compile_security_requirement(
lists:sort(maps:to_list(Requirement)), Schemes, []) of
{ok, Compiled} ->
case valid_security_combination(Compiled) of
true -> compile_security_requirements(
Rest, Schemes, [Compiled | Acc]);
false -> {error, conflicting_security_requirement}
end;
{error, _} = Error -> Error
end;
compile_security_requirements(_Security, _Schemes, _Acc) ->
{error, invalid_security_requirement}.
compile_security_requirement([], _Schemes, Acc) ->
{ok, lists:reverse(Acc)};
compile_security_requirement([{Name, Scopes} | Rest], Schemes, Acc)
when is_binary(Name), is_list(Scopes) ->
case maps:find(Name, Schemes) of
{ok, Scheme} ->
case valid_required_scopes(Scheme, Scopes) of
true ->
compile_security_requirement(
Rest, Schemes,
[#{scheme => Scheme,
scopes => lists:usort(Scopes)} | Acc]);
false -> {error, invalid_security_scopes}
end;
error -> {error, unknown_security_scheme}
end;
compile_security_requirement(_Requirement, _Schemes, _Acc) ->
{error, invalid_security_requirement}.
valid_required_scopes(#{type := oauth2, declared_scopes := Declared}, Scopes) ->
lists:all(fun is_binary/1, Scopes) andalso
lists:all(fun(Scope) -> lists:member(Scope, Declared) end, Scopes);
valid_required_scopes(_Scheme, []) -> true;
valid_required_scopes(_Scheme, _Scopes) -> false.
valid_security_combination(Requirement) ->
Placements = [{maps:get(location, maps:get(scheme, Item)),
maps:get(parameter_name, maps:get(scheme, Item))}
|| Item <- Requirement],
length(Placements) =:= length(lists:usort(Placements)).
security_parameter_conflicts(Security, Parameters) ->
SecurityPlacements = lists:usort(
lists:flatmap(
fun(Requirement) ->
[{maps:get(location, maps:get(scheme, Item)),
maps:get(parameter_name, maps:get(scheme, Item))}
|| Item <- Requirement]
end, Security)),
ParameterPlacements = [{maps:get(location, P), maps:get(request_name, P)}
|| P <- Parameters],
[Placement || Placement <- SecurityPlacements,
lists:member(Placement, ParameterPlacements)].
operation_base_url(Operation, PathItem, Spec, Policy) ->
Servers = case maps:find(<<"servers">>, Operation) of
{ok, Value} -> Value;
error ->
case maps:find(<<"servers">>, PathItem) of
{ok, Value} -> Value;
error -> maps:get(<<"servers">>, Spec, undefined)
end
end,
server_url(Servers, Policy).
server_url(undefined, #{base_url := undefined}) ->
{error, missing_openapi_server};
server_url(undefined, #{base_url := BaseUrl}) -> {ok, BaseUrl};
server_url([#{<<"url">> := Url}], Policy) when is_binary(Url) ->
case binary:match(Url, <<"{">>) =:= nomatch andalso
binary:match(Url, <<"}">>) =:= nomatch of
true -> resolve_server_url(Url, Policy);
false -> {error, server_variables_not_supported}
end;
server_url(_Servers, _Policy) ->
{error, multiple_or_invalid_servers}.
resolve_server_url(Url, Policy) ->
case uri_string:parse(Url) of
#{scheme := _, host := _} -> validate_base_url(Url, Policy);
#{path := _} ->
case maps:get(base_url, Policy) of
undefined -> {error, relative_server_without_base_url};
Base ->
try uri_string:resolve(Url, Base) of
Resolved -> validate_base_url(Resolved, Policy)
catch
_:_ -> {error, invalid_openapi_server}
end
end;
_ -> {error, invalid_openapi_server}
end.
validate_base_url(Url, Policy) when is_binary(Url) ->
case safe_parse_url(Url) of
{ok, Uri} ->
case maps:is_key(userinfo, Uri) orelse
maps:is_key(query, Uri) orelse maps:is_key(fragment, Uri) of
true -> {error, unsafe_openapi_server};
false ->
case validate_uri_policy(Uri, Policy) of
{ok, SafeUri} ->
Path = maps:get(path, SafeUri, <<>>),
{ok, uri_string:recompose(SafeUri#{path => Path})};
{error, _} = Error -> Error
end
end;
{error, _} = Error -> Error
end.
safe_parse_url(Url) ->
try uri_string:parse(Url) of
Uri when is_map(Uri) -> {ok, Uri};
_ -> {error, invalid_url}
catch
_:_ -> {error, invalid_url}
end.
validate_uri_policy(#{scheme := Scheme0, host := Host0} = Uri, Policy)
when is_binary(Scheme0), is_binary(Host0) ->
Scheme = lower_binary(Scheme0),
case canonical_host(Host0) of
{ok, Host} ->
AllowedSchemes = maps:get(allowed_schemes, Policy),
AllowedHosts = maps:get(allowed_hosts, Policy),
AllowPrivate = maps:get(allow_private_hosts, Policy),
case lists:member(Scheme, AllowedSchemes) andalso
lists:member(Host, AllowedHosts) andalso
(AllowPrivate orelse not private_host(Host)) of
true -> {ok, Uri#{scheme => Scheme, host => Host}};
false -> {error, openapi_target_not_allowed}
end;
error -> {error, openapi_target_not_allowed}
end;
validate_uri_policy(_Uri, _Policy) ->
{error, invalid_url}.
canonical_host(Host0) ->
Host1 = lower_binary(Host0),
Host = strip_trailing_dot(Host1),
case byte_size(Host) > 0 andalso byte_size(Host) =< 253 andalso
re:run(Host, <<"^[a-z0-9.-]+$">>, [{capture, none}]) =:= match andalso
binary:match(Host, <<"..">>) =:= nomatch of
true -> {ok, Host};
false ->
%% IP literals are parsed separately; they are allowed only behind
%% the explicit private-host override.
case inet:parse_address(binary_to_list(Host)) of
{ok, _} -> {ok, Host};
_ -> error
end
end.
strip_trailing_dot(<<>>) -> <<>>;
strip_trailing_dot(Binary) ->
case binary:last(Binary) of
$. -> binary:part(Binary, 0, byte_size(Binary) - 1);
_ -> Binary
end.
private_host(Host) ->
Host =:= <<"localhost">> orelse has_suffix(Host, <<".localhost">>) orelse
has_suffix(Host, <<".local">>) orelse
case inet:parse_address(binary_to_list(Host)) of
{ok, _Address} -> true;
_ -> false
end.
run_bounded(Toolset, Operation, Args, Timeout) ->
Owner = self(),
Deadline = erlang:monotonic_time(millisecond) + Timeout,
ReplyAlias = erlang:alias([explicit_unalias]),
ReplyRef = make_ref(),
Worker = fun() ->
ok = start_execution_owner_watchdog(Owner, self()),
Outcome = try execute_operation(Toolset, Operation, Args) of
Result -> Result
catch
_Class:_Reason -> {error, openapi_execution_failed}
end,
SafeOutcome = bounded_execution_outcome(Outcome),
CompletedAt = erlang:monotonic_time(millisecond),
_ = erlang:send(
ReplyAlias,
{openapi_execution_result, ReplyRef, self(),
CompletedAt, SafeOutcome},
[noconnect, nosuspend]),
ok
end,
SpawnOptions =
[monitor, {message_queue_data, off_heap},
{max_heap_size,
#{size => ?EXECUTION_MAX_HEAP_WORDS, kill => true,
error_logger => false, include_shared_binaries => true}}],
try erlang:spawn_opt(Worker, SpawnOptions) of
{Pid, MonitorRef} ->
await_bounded_execution(
Pid, MonitorRef, ReplyAlias, ReplyRef, Deadline)
catch
_:_ ->
_ = erlang:unalias(ReplyAlias),
{error, openapi_execution_failed}
end.
await_bounded_execution(Pid, MonitorRef, ReplyAlias, ReplyRef, Deadline) ->
receive
{openapi_execution_result, ReplyRef, Pid, CompletedAt, Result} ->
_ = erlang:unalias(ReplyAlias),
_ = erlang:demonitor(MonitorRef, [flush]),
completed_execution_result(CompletedAt, Deadline, Result);
{'DOWN', MonitorRef, process, Pid, _OpaqueReason} ->
_ = erlang:unalias(ReplyAlias),
{error, openapi_execution_failed}
after remaining_deadline(Deadline) ->
_ = erlang:unalias(ReplyAlias),
exit(Pid, kill),
_ = erlang:demonitor(MonitorRef, [flush]),
{error, timeout}
end.
completed_execution_result(CompletedAt, Deadline, _Result)
when CompletedAt > Deadline ->
{error, timeout};
completed_execution_result(_CompletedAt, _Deadline, Result) ->
Result.
bounded_execution_outcome(Outcome) ->
try erlang:external_size(Outcome) =< ?EXECUTION_MAX_RESULT_BYTES of
true -> Outcome;
false -> {error, openapi_execution_failed}
catch
_:_ -> {error, openapi_execution_failed}
end.
start_execution_owner_watchdog(Owner, ExecutionWorker) ->
Watchdog = fun() -> execution_owner_watchdog(Owner, ExecutionWorker) end,
SpawnOptions =
[{message_queue_data, off_heap},
{max_heap_size,
#{size => ?EXECUTION_WATCHDOG_MAX_HEAP_WORDS, kill => true,
error_logger => false, include_shared_binaries => true}}],
try erlang:spawn_opt(Watchdog, SpawnOptions) of
WatchdogPid when is_pid(WatchdogPid) -> ok
catch
_:_ -> error
end.
execution_owner_watchdog(Owner, ExecutionWorker) ->
OwnerMonitor = erlang:monitor(process, Owner),
WorkerMonitor = erlang:monitor(process, ExecutionWorker),
receive
{'DOWN', OwnerMonitor, process, Owner, _OpaqueReason} ->
exit(ExecutionWorker, kill),
_ = erlang:demonitor(WorkerMonitor, [flush]),
ok;
{'DOWN', WorkerMonitor, process, ExecutionWorker, _OpaqueReason} ->
_ = erlang:demonitor(OwnerMonitor, [flush]),
ok
end.
remaining_deadline(Deadline) ->
erlang:max(0, Deadline - erlang:monotonic_time(millisecond)).
execute_operation(#toolset{transport = Transport, auth = Auth},
Operation, Args) ->
InputSchema = maps:get(input_schema, Operation),
case adk_json_schema:validate(InputSchema, Args) of
{ok, CanonicalArgs} when is_map(CanonicalArgs) ->
case build_unauthorized_request(Operation, CanonicalArgs) of
{ok, Url0, Headers0, Query0, Body} ->
case apply_security(maps:get(security, Operation), Auth,
maps:get(name, Operation),
Headers0, Query0) of
{ok, Headers, Query, Seeds} ->
send_openapi_request(
Transport, Operation, Url0, Headers, Query,
Body, Seeds);
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} -> {error, invalid_arguments};
_ -> {error, invalid_arguments}
end.
build_unauthorized_request(Operation, Args) ->
Parameters = maps:get(parameters, Operation),
case encode_parameters(Parameters, Args,
maps:get(path, Operation), [], []) of
{ok, Path, Headers, Query} ->
case encode_body(maps:get(body, Operation), Args,
maps:get(policy, Operation)) of
{ok, Body, BodyHeaders} ->
BaseUrl = maps:get(base_url, Operation),
case join_base_path(BaseUrl, Path) of
{ok, Url} ->
{ok, Url, BodyHeaders ++ Headers, Query, Body};
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end;
{error, _} = Error -> Error
end.
encode_parameters([], _Args, Path, Headers, Query) ->
{ok, Path, lists:reverse(Headers), lists:reverse(Query)};
encode_parameters([Parameter | Rest], Args, Path, Headers, Query) ->
Name = maps:get(name, Parameter),
case maps:find(Name, Args) of
error -> encode_parameters(Rest, Args, Path, Headers, Query);
{ok, Value} ->
case encode_parameter(Parameter, Value, Path, Headers, Query) of
{ok, Path1, Headers1, Query1} ->
encode_parameters(Rest, Args, Path1,
Headers1, Query1);
{error, _} = Error -> Error
end
end.
encode_parameter(#{location := path, name := Name}, Value,
Path, Headers, Query) ->
case path_value(Value) of
{ok, Quoted} ->
Placeholder = <<"{", Name/binary, "}">>,
{ok, binary:replace(Path, Placeholder, Quoted, [global]),
Headers, Query};
error -> {error, invalid_arguments}
end;
encode_parameter(#{location := header, request_name := Name}, Value,
Path, Headers, Query) ->
case simple_value(Value) of
{ok, Encoded} ->
case safe_header_value(Encoded) of
true -> {ok, Path, [{Name, Encoded} | Headers], Query};
false -> {error, invalid_arguments}
end;
error -> {error, invalid_arguments}
end;
encode_parameter(#{location := query, request_name := Name,
explode := Explode}, Value,
Path, Headers, Query) ->
case query_values(Name, Value, Explode) of
{ok, Pairs} -> {ok, Path, Headers, lists:reverse(Pairs) ++ Query};
error -> {error, invalid_arguments}
end.
simple_value(Value) when is_list(Value) ->
simple_list(Value, []);
simple_value(Value) -> scalar_binary(Value).
path_value(Values) when is_list(Values) ->
path_list(Values, []);
path_value(Value) ->
case scalar_binary(Value) of
{ok, Binary} -> {ok, uri_string:quote(Binary)};
error -> error
end.
path_list([], Acc) ->
{ok, join_binary(lists:reverse(Acc), <<",">>)};
path_list([Value | Rest], Acc) ->
case scalar_binary(Value) of
{ok, Binary} -> path_list(Rest, [uri_string:quote(Binary) | Acc]);
error -> error
end;
path_list(_Improper, _Acc) -> error.
simple_list([], Acc) -> {ok, join_binary(lists:reverse(Acc), <<",">>)};
simple_list([Value | Rest], Acc) ->
case scalar_binary(Value) of
{ok, Binary} -> simple_list(Rest, [Binary | Acc]);
error -> error
end;
simple_list(_Improper, _Acc) -> error.
scalar_binary(Value) when is_binary(Value) -> {ok, Value};
scalar_binary(Value) when is_integer(Value) -> {ok, integer_to_binary(Value)};
scalar_binary(Value) when is_float(Value) ->
{ok, float_to_binary(Value, [short])};
scalar_binary(true) -> {ok, <<"true">>};
scalar_binary(false) -> {ok, <<"false">>};
scalar_binary(null) -> {ok, <<"null">>};
scalar_binary(_) -> error.
query_values(Name, Values, true) when is_list(Values) ->
query_value_pairs(Name, Values, []);
query_values(Name, Values, false) when is_list(Values) ->
case simple_value(Values) of
{ok, Joined} -> {ok, [{Name, Joined}]};
error -> error
end;
query_values(Name, Value, _Explode) ->
case scalar_binary(Value) of
{ok, Binary} -> {ok, [{Name, Binary}]};
error -> error
end.
query_value_pairs(_Name, [], Acc) -> {ok, lists:reverse(Acc)};
query_value_pairs(Name, [Value | Rest], Acc) ->
case scalar_binary(Value) of
{ok, Binary} -> query_value_pairs(Name, Rest,
[{Name, Binary} | Acc]);
error -> error
end;
query_value_pairs(_Name, _Improper, _Acc) -> error.
encode_body(undefined, _Args, _Policy) -> {ok, <<>>, []};
encode_body(#{media_type := MediaType}, Args, Policy) ->
case maps:find(<<"body">>, Args) of
error -> {ok, <<>>, []};
{ok, Value} ->
try jsx:encode(Value) of
Body ->
case byte_size(Body) =<
maps:get(max_request_body_bytes, Policy) of
true ->
{ok, Body,
[{<<"content-type">>, MediaType}]};
false -> {error, request_body_too_large}
end
catch
_:_ -> {error, invalid_arguments}
end
end.
join_base_path(BaseUrl, OperationPath) ->
case safe_parse_url(BaseUrl) of
{ok, Uri} ->
BasePath = maps:get(path, Uri, <<>>),
Path = join_paths(BasePath, OperationPath),
{ok, uri_string:recompose(Uri#{path => Path})};
{error, _} = Error -> Error
end.
join_paths(<<>>, OperationPath) -> OperationPath;
join_paths(<<"/">>, OperationPath) -> OperationPath;
join_paths(BasePath, OperationPath) ->
Base = strip_trailing_slash(BasePath),
<<Base/binary, OperationPath/binary>>.
strip_trailing_slash(<<>>) -> <<>>;
strip_trailing_slash(Binary) ->
case binary:last(Binary) of
$/ -> binary:part(Binary, 0, byte_size(Binary) - 1);
_ -> Binary
end.
apply_security([], _Auth, _OperationId, Headers, Query) ->
{ok, Headers, Query, []};
apply_security(Alternatives, undefined, _OperationId, Headers, Query) ->
case lists:any(fun(Requirement) -> Requirement =:= [] end,
Alternatives) of
true -> {ok, Headers, Query, []};
false -> {error, authentication_required}
end;
apply_security(Alternatives, Auth, OperationId, Headers, Query) ->
try_security_alternatives(Alternatives, Auth, OperationId,
Headers, Query).
try_security_alternatives([], _Auth, _OperationId, _Headers, _Query) ->
{error, authentication_failed};
try_security_alternatives([Requirement | Rest], Auth, OperationId,
Headers, Query) ->
case resolve_security_requirement(Requirement, Auth, OperationId,
Headers, Query, []) of
{ok, _Headers, _Query, _Seeds} = Ok -> Ok;
{error, _} -> try_security_alternatives(
Rest, Auth, OperationId, Headers, Query)
end.
resolve_security_requirement([], _Auth, _OperationId,
Headers, Query, Seeds) ->
{ok, Headers, Query, lists:usort(Seeds)};
resolve_security_requirement([Item | Rest], {Module, Handle} = Auth,
OperationId, Headers, Query, Seeds) ->
Scheme = maps:get(scheme, Item),
Request = auth_request(OperationId, Scheme, maps:get(scopes, Item)),
Result = try Module:resolve(Handle, Request) of
Value -> Value
catch
_:_ -> {error, auth_manager_failed}
end,
case apply_credential(Scheme, Result, Headers, Query) of
{ok, Headers1, Query1, Secret} ->
resolve_security_requirement(Rest, Auth, OperationId,
Headers1, Query1,
[Secret | Seeds]);
{error, _} = Error -> Error
end.
auth_request(OperationId, Scheme, Scopes) ->
Base = #{operation_id => OperationId,
scheme_name => maps:get(name, Scheme),
scheme_type => maps:get(type, Scheme),
scopes => Scopes},
case maps:get(type, Scheme) of
api_key -> Base#{location => maps:get(location, Scheme),
parameter_name => maps:get(parameter_name, Scheme)};
_ -> Base
end.
apply_credential(#{type := api_key, location := header,
parameter_name := Name},
{ok, {api_key, Secret}}, Headers, Query)
when is_binary(Secret), byte_size(Secret) > 0 ->
case safe_header_value(Secret) andalso
not header_exists(Name, Headers) of
true -> {ok, [{Name, Secret} | Headers], Query, Secret};
false -> {error, invalid_auth_credential}
end;
apply_credential(#{type := api_key, location := query,
parameter_name := Name},
{ok, {api_key, Secret}}, Headers, Query)
when is_binary(Secret), byte_size(Secret) > 0 ->
case valid_utf8(Secret) andalso not lists:keymember(Name, 1, Query) of
true -> {ok, Headers, [{Name, Secret} | Query], Secret};
false -> {error, invalid_auth_credential}
end;
apply_credential(#{type := Type}, {ok, {bearer, Secret}}, Headers, Query)
when (Type =:= bearer orelse Type =:= oauth2),
is_binary(Secret), byte_size(Secret) > 0 ->
case safe_header_value(Secret) andalso
binary:match(Secret, <<" ">>) =:= nomatch andalso
not header_exists(<<"authorization">>, Headers) of
true ->
Value = <<"Bearer ", Secret/binary>>,
{ok, [{<<"authorization">>, Value} | Headers],
Query, Secret};
false -> {error, invalid_auth_credential}
end;
apply_credential(_Scheme, {error, _Reason}, _Headers, _Query) ->
{error, authentication_failed};
apply_credential(_Scheme, _Result, _Headers, _Query) ->
{error, invalid_auth_credential}.
header_exists(Name, Headers) ->
Lower = lower_binary(Name),
lists:any(fun({HeaderName, _}) -> lower_binary(HeaderName) =:= Lower end,
Headers).
safe_header_value(Value) ->
safe_header_bytes(Value).
safe_header_bytes(<<>>) -> true;
safe_header_bytes(<<Byte, Rest/binary>>)
when Byte >= 32, Byte =/= 127 ->
safe_header_bytes(Rest);
safe_header_bytes(_) -> false.
valid_utf8(Value) ->
case unicode:characters_to_binary(Value, utf8, utf8) of
Value -> true;
_ -> false
end.
send_openapi_request({TransportModule, TransportHandle}, Operation,
Url0, Headers0, Query, Body, Seeds) ->
Url = append_query(Url0, Query),
Policy = maps:get(policy, Operation),
case safe_parse_url(Url) of
{ok, Uri} ->
case validate_uri_policy(Uri, Policy) of
{ok, _} ->
Headers = lists:sort(Headers0),
Request = #{method => maps:get(method, Operation),
url => Url,
headers => Headers,
body => Body,
timeout_ms => maps:get(timeout_ms, Policy),
max_response_bytes =>
maps:get(max_response_bytes, Policy),
follow_redirects => false,
allowed_schemes =>
maps:get(allowed_schemes, Policy),
allowed_hosts =>
maps:get(allowed_hosts, Policy),
allow_private_hosts =>
maps:get(allow_private_hosts, Policy)},
TransportResult = try
TransportModule:request(TransportHandle, Request)
catch
_:_ -> {error, transport_failed}
end,
handle_transport_result(TransportResult, Operation,
Seeds);
{error, _} -> {error, openapi_target_not_allowed}
end;
{error, _} -> {error, invalid_url}
end.
append_query(Url, []) -> Url;
append_query(Url, Pairs) ->
Encoded = join_binary(
[<<(uri_string:quote(Name))/binary, "=",
(uri_string:quote(Value))/binary>>
|| {Name, Value} <- Pairs], <<"&">>),
<<Url/binary, "?", Encoded/binary>>.
handle_transport_result({ok, Response}, Operation, Seeds)
when is_map(Response) ->
case {maps:get(status, Response, undefined),
maps:get(body, Response, undefined)} of
{Status, Body} when is_integer(Status), Status >= 100, Status =< 599,
is_binary(Body) ->
Policy = maps:get(policy, Operation),
case byte_size(Body) =< maps:get(max_response_bytes, Policy) of
false -> {error, response_too_large};
true -> handle_http_status(Status, Body,
maps:get(headers, Response, []),
Operation, Seeds)
end;
_ -> {error, invalid_transport_response}
end;
handle_transport_result({error, timeout}, _Operation, _Seeds) ->
{error, timeout};
handle_transport_result({error, _Reason}, _Operation, _Seeds) ->
{error, transport_error};
handle_transport_result(_Result, _Operation, _Seeds) ->
{error, invalid_transport_response}.
handle_http_status(Status, _Body, _Headers, _Operation, _Seeds)
when Status >= 300, Status < 400 ->
{error, {redirect_rejected, Status}};
handle_http_status(Status, Body, Headers, Operation, Seeds)
when Status >= 200, Status < 300 ->
case response_contract(Status, maps:get(responses, Operation)) of
{ok, Contract} ->
decode_success_response(Status, Body, Headers, Contract, Seeds);
error -> {error, {unexpected_http_status, Status}}
end;
handle_http_status(Status, _Body, _Headers, _Operation, _Seeds) ->
{error, {http_status, Status}}.
response_contract(Status, Responses) ->
Exact = integer_to_binary(Status),
Class = <<(integer_to_binary(Status div 100))/binary, "XX">>,
case maps:find(Exact, Responses) of
{ok, Contract} -> {ok, Contract};
error ->
case maps:find(Class, Responses) of
{ok, Contract} -> {ok, Contract};
error -> maps:find(<<"default">>, Responses)
end
end.
decode_success_response(Status, <<>>, _Headers,
#{schema := undefined}, _Seeds) ->
{ok, #{<<"status">> => Status, <<"data">> => null}};
decode_success_response(Status, Body, Headers, Contract, Seeds) ->
case response_is_json(Contract, Headers) of
false -> {error, unsupported_response_content_type};
true ->
try jsx:decode(Body, [return_maps]) of
Decoded -> validate_response_data(Status, Decoded,
Contract, Seeds)
catch
_:_ -> {error, invalid_json_response}
end
end.
response_is_json(#{media_type := MediaType}, _Headers)
when is_binary(MediaType) -> json_media_type(MediaType);
response_is_json(#{media_type := non_json}, _Headers) -> false;
response_is_json(_Contract, Headers) ->
case response_header(<<"content-type">>, Headers) of
{ok, Type} -> json_media_type(Type);
error -> false
end.
response_header(Name, Headers) when is_list(Headers) ->
Lower = lower_binary(Name),
case lists:search(
fun({Key, Value}) ->
is_binary(Key) andalso is_binary(Value) andalso
lower_binary(Key) =:= Lower;
(_) -> false
end, Headers) of
{value, {_Key, Value}} -> {ok, Value};
false -> error
end;
response_header(Name, Headers) when is_map(Headers) ->
response_header(Name, maps:to_list(Headers));
response_header(_Name, _Headers) -> error.
validate_response_data(Status, Decoded, #{schema := undefined}, Seeds) ->
safe_response_result(Status, Decoded, Seeds);
validate_response_data(Status, Decoded, #{schema := Schema}, Seeds) ->
case adk_json_schema:validate(Schema, Decoded) of
{ok, Checked} -> safe_response_result(Status, Checked, Seeds);
{error, _} -> {error, response_schema_mismatch}
end.
safe_response_result(Status, Data, Seeds) ->
case adk_context_guard:sanitize_value(Data) of
{ok, Safe0} ->
Safe = adk_secret_redactor:redact(Safe0, Seeds),
{ok, #{<<"status">> => Status, <<"data">> => Safe}};
{error, _} -> {error, invalid_json_response}
end.
join_binary([], _Separator) -> <<>>;
join_binary([Only], _Separator) -> Only;
join_binary([First | Rest], Separator) ->
lists:foldl(fun(Value, Acc) ->
<<Acc/binary, Separator/binary, Value/binary>>
end, First, Rest).
lower_binary(Binary) when is_binary(Binary) ->
try string:lowercase(Binary) of
Lower when is_binary(Lower) -> Lower
catch
_:_ -> Binary
end.
has_suffix(Binary, Suffix) when byte_size(Binary) >= byte_size(Suffix) ->
Start = byte_size(Binary) - byte_size(Suffix),
binary:part(Binary, Start, byte_size(Suffix)) =:= Suffix;
has_suffix(_Binary, _Suffix) -> false.