Warn if payload headers override previous headers.

When rest-client overrides existing headers due to headers generated
from the HTTP payload, warn the user that there is a conflict. This is
often caused by user error due to confusing rest-client API and docs.

lib/restclient/request.rb

@@ -432,7 +432,26 @@ module RestClient
     #
     def make_headers(user_headers)
       headers = stringify_headers(default_headers).merge(stringify_headers(user_headers))
-      headers.merge!(@payload.headers) if @payload
+
+      # override headers from the payload (e.g. Content-Type, Content-Length)
+      if @payload
+        payload_headers = @payload.headers
+
+        # Warn the user if we override any headers that were previously
+        # present. This usually indicates that rest-client was passed
+        # conflicting information, e.g. if it was asked to render a payload as
+        # x-www-form-urlencoded but a Content-Type application/json was
+        # also supplied by the user.
+        payload_headers.each_pair do |key, val|
+          if headers.include?(key)
+            warn("warning: Overriding #{key.inspect} header " +
+                 "#{headers.fetch(key).inspect} with #{val.inspect} " +
+                 "due to payload")
+          end
+        end
+
+        headers.merge!(payload_headers)
+      end
 
       # merge in cookies
       cookies = make_cookie_header